win32-api 1.2.0 → 1.3.0

data/CHANGES

@@ -1,3 +1,38 @@
+= 1.3.0 - 1-Jan-2009
+* Fixed RubyForge bug #23395, which was caused by inadvertently modifying
+  a variable within a loop. This caused callbacks to fail in certain
+  situations.
+* Added the Win32::API::LoadLibraryError and Win32::API::PrototypeError classes
+  to provide more fine grained handling of possible error conditions in the
+  constructor. These are both subclasses of Win32::API::Error.
+* Removed the Win32::API::CallbackError class.
+* Changed the upper limit on prototypes from 16 to 20. It turns out that
+  there are actually Windows functions with more than 16 prototypes.
+* Refactored a high iteration test so that it counts as only one test
+  instead of 1000.
+
+= 1.2.2 - 27-Nov-2008
+* Fixed bug in the error message for illegal prototypes and illegal return
+  types where the character in question would come out as empty or garbage.
+* Passing a bad return type to Win32::API::Callback now raises an error.
+* Updated the error message for illegal return types to say, "Illegal return
+  type" instead of "Illegal prototype" as it did previously.
+* The error message for a bad function name passed to Win32::API.new now
+  matches JRuby's FFI error message.
+* Improved the handling of msvcrt functions with regards to skipping 'A'
+  and 'W' checks. Previously it was checking against the literal string
+  'msvcrt'. Now it checks against any string that starts with 'msvcr'.
+* Added test-unit 2.x as a prerequisite.
+* Added tests for the Win32::API::Callback#address method.
+* Added tests to all Win32::API classes that explicitly check error messages.
+
+= 1.2.1 - 14-Nov-2008
+* Fixed and updated callback handling.
+* Fixed wide string return handling for pointers and strings.
+* Added the Win32::API::Callback#address instance method.
+* All errors are now in English instead of your native language, because
+  that's what Ruby itself does.
+
 = 1.2.0 - 22-Jul-2008
 * Added support for the 'S' (string) prototype and return type. It can be
   used instead of 'P' (pointer) for const char*.

data/MANIFEST

@@ -1,10 +1,10 @@
-* CHANGES
-* MANIFEST
-* README
-* Rakefile
-* win32-api.gemspec
-* ext/extconf.rb
-* ext/win32/api.c
-* test/test_win32_api.rb
-* test/test_win32_api_callback.rb
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* win32-api.gemspec
+* ext/extconf.rb
+* ext/win32/api.c
+* test/test_win32_api.rb
+* test/test_win32_api_callback.rb
 * test/test_win32_api_function.rb

data/README

@@ -70,7 +70,7 @@
    instance variable names with proper accessors, removing support for lower
    case prototype and return value characters that no one used in practice,
    better naming conventions, the addition of RDoc ready comments and,
-   especially, callback support.
+   especially, callback and raw function pointer support.
    
    Most importantly, we can now add, modify and fix any features that we feel
    best benefit our end users.

data/ext/win32/api.c

@@ -2,7 +2,7 @@
 #include <windows.h>
 
 #define MAX_BUF 1024
-#define WINDOWS_API_VERSION "1.2.0"
+#define WINDOWS_API_VERSION "1.3.0"
 
 #define _T_VOID     0
 #define _T_LONG     1
@@ -11,13 +11,14 @@
 #define _T_CALLBACK 4
 #define _T_STRING   5
 
-VALUE cAPIError, cCallbackError;
+VALUE cAPIError, cAPIProtoError, cAPILoadError;
+static VALUE ActiveCallback = Qnil;
 
 typedef struct {
     HANDLE library;
     FARPROC function;
     int return_type;
-    int prototype[16];
+    int prototype[20];
 } Win32API;
 
 static void api_free(Win32API* ptr){
@@ -34,7 +35,10 @@ static VALUE api_allocate(VALUE klass){
 }
 
 /* Helper function that converts the error number returned by GetLastError()
- * into a human readable string. Internal use only.
+ * into a human readable string. Note that we always use English for error
+ * output because that's what Ruby itself does.
+ *
+ * Internal use only.
  */
 char* StringError(DWORD dwError){
    LPVOID lpMsgBuf;
@@ -48,7 +52,7 @@ char* StringError(DWORD dwError){
       FORMAT_MESSAGE_IGNORE_INSERTS,
       NULL,
       dwError,
-      MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+      MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US),
       (LPSTR)&lpMsgBuf,
       0,
       NULL
@@ -74,71 +78,86 @@ char* StringError(DWORD dwError){
 /*
  * call-seq:
  *    Win32::API::Callback.new(prototype, return='L'){ |proto| ... }
- * 
+ *
  * Creates and returns a new Win32::API::Callback object. The prototype
  * arguments are yielded back to the block in the same order they were
  * declared.
- * 
+ *
  * The +prototype+ is the function prototype for the callback function. This
  * is a string. The possible valid characters are 'I' (integer), 'L' (long),
  * 'V' (void), 'P' (pointer) or 'S' (string). Unlike API objects, API::Callback
  * objects do not have a default prototype.
- * 
+ *
  * The +return+ argument is the return type for the callback function. The
  * valid characters are the same as for the +prototype+. The default is
  * 'L' (long).
- * 
+ *
  * Example:
  *    require 'win32/api'
  *    include Win32
- * 
+ *
  *    EnumWindows = API.new('EnumWindows', 'KP', 'L', 'user32')
  *    GetWindowText = API.new('GetWindowText', 'LPI', 'I', 'user32')
- * 
+ *
  *    EnumWindowsProc = API::Callback.new('LP', 'I'){ |handle, param|
  *       buf = "\0" * 200
  *       GetWindowText.call(handle, buf, 200);
  *       puts buf.strip unless buf.strip.empty?
  *       buf.index(param).nil? ? true : false
  *    }
- *  
+ *
  *    EnumWindows.call(EnumWindowsProc, 'UEDIT32')
  */
 static VALUE callback_init(int argc, VALUE* argv, VALUE self)
 {
+   extern void *CallbackTable[];
    VALUE v_proto, v_return, v_proc;
    int i;
-    
+
    rb_scan_args(argc, argv, "11&", &v_proto, &v_return, &v_proc);
-   
+
    /* Validate prototype characters */
    for(i = 0; i < RSTRING(v_proto)->len; i++){
       switch(RSTRING(v_proto)->ptr[i]){
          case 'I': case 'L': case 'P': case 'V': case 'S':
             break;
          default:
-            rb_raise(cCallbackError, "Illegal prototype '%c'",
-               RSTRING(v_proto)->ptr[i]);
+            rb_raise(cAPIProtoError, "Illegal prototype '%c'",
+               RSTRING(v_proto)->ptr[i]
+            );
       }
    }
 
-   if(NIL_P(v_return) || RARRAY(v_return)->len == 0)
+   if(NIL_P(v_return) || RARRAY(v_return)->len == 0){
       v_return = rb_str_new2("L");
+   }
+   else{
+      switch(*(char*)RSTRING(v_return)->ptr){
+         case 'I': case 'L': case 'P': case 'V': case 'S':
+            break;
+         default:
+            rb_raise(cAPIProtoError, "Illegal return type '%s'",
+               RSTRING(v_return)->ptr
+            );
+      }
+   }
 
    rb_iv_set(self, "@function", v_proc);
    rb_iv_set(self, "@prototype", v_proto);
    rb_iv_set(self, "@return_type", v_return);
-    
+   rb_iv_set(self, "@address", ULONG2NUM((LPARAM)CallbackTable[RSTRING(v_proto)->len]));
+   ActiveCallback = self;
+
    return self;
 }
 
 /*
  * call-seq:
  *    Win32::API.new(function, prototype='V', return='L', dll='kernel32')
- * 
+ *
  * Creates and returns a new Win32::API object. The +function+ is the name
  * of the Windows function.
- * 
+ *
  * The +prototype+ is the function prototype for +function+. This can be a
  * string or an array of characters.  The possible valid characters are 'I'
  * (integer), 'L' (long), 'V' (void), 'P' (pointer), 'K' (callback) or 'S'
@@ -148,27 +167,27 @@ static VALUE callback_init(int argc, VALUE* argv, VALUE self)
  *
  * Constant (const char*) strings should use 'S'. Pass by reference string
  * buffers should use 'P'. The former is faster, but cannot be modified.
- * 
+ *
  * The +return+ argument is the return type for the function.  The valid
  * characters are the same as for the +prototype+.  The default is 'L' (long).
- * 
+ *
  * The +dll+ is the name of the DLL file that the function is exported from.
  * The default is 'kernel32'.
- * 
+ *
  * If the function cannot be found then an API::Error is raised (a subclass
  * of RuntimeError).
- * 
+ *
  * Example:
- * 
+ *
  *    require 'win32/api'
  *    include Win32
- * 
+ *
  *    buf = 0.chr * 260
  *    len = [buf.length].pack('L')
- *  
+ *
  *    GetUserName = API.new('GetUserName', 'PP', 'I', 'advapi32')
  *    GetUserName.call(buf, len)
- * 
+ *
  *    puts buf.strip
  */
 static VALUE api_init(int argc, VALUE* argv, VALUE self)
@@ -180,9 +199,9 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
    char* first  = "A";
    char* second = "W";
    VALUE v_proc, v_proto, v_return, v_dll;
-   
+
    rb_scan_args(argc, argv, "13", &v_proc, &v_proto, &v_return, &v_dll);
-   
+
    Data_Get_Struct(self, Win32API, ptr);
 
    // Convert a string prototype to an array of characters
@@ -195,17 +214,17 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
       rb_ary_push(v_proto, rb_str_new2("V"));
    }
 
-   // Set an arbitrary limit of 16 parameters
-   if(16 < RARRAY(v_proto)->len)
+   // Set an arbitrary limit of 20 parameters
+   if(20 < RARRAY(v_proto)->len)
       rb_raise(rb_eArgError, "too many parameters: %d\n", RARRAY(v_proto)->len);
-   
+
    // Set the default dll to 'kernel32'
    if(NIL_P(v_dll))
-   	v_dll = rb_str_new2("kernel32");
-   	
+      v_dll = rb_str_new2("kernel32");
+
    // Set the default return type to 'L' (DWORD)
    if(NIL_P(v_return))
-   	v_return = rb_str_new2("L");
+      v_return = rb_str_new2("L");
 
    SafeStringValue(v_dll);
    SafeStringValue(v_proc);
@@ -214,7 +233,7 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
 
    // The most likely cause of failure is a bad DLL load path
    if(!hLibrary){
-      rb_raise(cAPIError, "LoadLibrary() function failed for '%s': %s",
+      rb_raise(cAPILoadError, "LoadLibrary() function failed for '%s': %s",
          RSTRING(v_dll)->ptr,
          StringError(GetLastError())
       );
@@ -236,10 +255,10 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
 
    // Skip the ANSI and Wide function checks for MSVCRT functions.
    if(!fProc){
-      if(!strcmp(RSTRING(v_dll)->ptr, "msvcrt")){
+      if(strstr(RSTRING(v_dll)->ptr, "msvcr")){
          rb_raise(
-            cAPIError,
-            "GetProcAddress() failed for '%s': %s",
+            cAPILoadError,
+            "Unable to load function '%s'",
             RSTRING(v_proc)->ptr,
             StringError(GetLastError())
          );
@@ -256,12 +275,11 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
 
             if(!fProc){
                rb_raise(
-                  cAPIError,
-                  "GetProcAddress() failed for '%s', '%s' and '%s': %s",
+                  cAPILoadError,
+                  "Unable to load function '%s', '%s', or '%s'",
                   RSTRING(v_proc)->ptr,
                   RSTRING(v_ascii)->ptr,
-                  RSTRING(v_unicode)->ptr,
-                  StringError(GetLastError())
+                  RSTRING(v_unicode)->ptr
                );
             }
             else{
@@ -303,7 +321,9 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
             ptr->prototype[i] = _T_STRING;
             break;
          default:
-            rb_raise(cAPIError, "Illegal prototype '%s'", RARRAY(v_proto)->ptr[i]);
+            rb_raise(cAPIProtoError, "Illegal prototype '%s'",
+               StringValuePtr(RARRAY(v_proto)->ptr[i])
+            );
       }
    }
 
@@ -333,7 +353,9 @@ static VALUE api_init(int argc, VALUE* argv, VALUE self)
             ptr->return_type = _T_STRING;
             break;
          default:
-            rb_raise(cAPIError, "Illegal prototype '%s'", RARRAY(v_proto)->ptr[i]);
+            rb_raise(cAPIProtoError, "Illegal return type '%s'",
+               RSTRING(v_return)->ptr
+            );
       }
    }
 
@@ -391,13 +413,13 @@ static VALUE func_init(int argc, VALUE* argv, VALUE self){
       rb_ary_push(v_proto, rb_str_new2("V"));
    }
 
-   // Set an arbitrary limit of 16 parameters
-   if(16 < RARRAY(v_proto)->len)
+   // Set an arbitrary limit of 20 parameters
+   if(20 < RARRAY(v_proto)->len)
       rb_raise(rb_eArgError, "too many parameters: %d\n", RARRAY(v_proto)->len);
 
    // Set the default return type to 'L' (DWORD)
    if(NIL_P(v_return))
-   	v_return = rb_str_new2("L");
+      v_return = rb_str_new2("L");
 
    ptr->function = (FARPROC)NUM2LONG(v_address);
 
@@ -425,7 +447,9 @@ static VALUE func_init(int argc, VALUE* argv, VALUE self){
             ptr->prototype[i] = _T_STRING;
             break;
          default:
-            rb_raise(cAPIError, "Illegal prototype '%s'", RARRAY(v_proto)->ptr[i]);
+            rb_raise(cAPIProtoError, "Illegal prototype '%s'",
+               StringValuePtr(RARRAY(v_proto)->ptr[i])
+            );
       }
    }
 
@@ -455,7 +479,9 @@ static VALUE func_init(int argc, VALUE* argv, VALUE self){
             ptr->return_type = _T_STRING;
             break;
          default:
-            rb_raise(cAPIError, "Illegal prototype '%s'", RARRAY(v_proto)->ptr[i]);
+            rb_raise(cAPIProtoError, "Illegal return type '%s'",
+               RSTRING(v_return)->ptr
+            );
       }
    }
 
@@ -467,95 +493,176 @@ static VALUE func_init(int argc, VALUE* argv, VALUE self){
 }
 
 typedef struct {
-   DWORD params[1];
-} PARAM;
+   DWORD params[20];
+} CALLPARAM;
 
-static VALUE ActiveCallback; 
 
-DWORD CallbackFunction(PARAM param)
+DWORD CallbackFunction(CALLPARAM param)
 {
     VALUE v_proto, v_return, v_proc, v_retval;
-    VALUE argv[16];
+    VALUE argv[20];
     int i, argc;
     char *a_proto;
     char *a_return;
-    
+
     if(!NIL_P(ActiveCallback)){
         v_proto = rb_iv_get(ActiveCallback, "@prototype");
         a_proto = RSTRING(v_proto)->ptr;
-        
+
         v_return = rb_iv_get(ActiveCallback, "@return_type");
         a_return = RSTRING(v_return)->ptr;
-        
+
         v_proc = rb_iv_get(ActiveCallback, "@function");
         argc = RSTRING(v_proto)->len;
-        
+
         for(i=0; i < RSTRING(v_proto)->len; i++){
            argv[i] = Qnil;
            switch(a_proto[i]){
-  	           case 'L':
-  	              argv[i] = ULONG2NUM(param.params[i]); 
-  	              break;
-  	           case 'P':
-  	              if(param.params[i])
-  	                 argv[i] = rb_str_new2((char *)param.params[i]);
-  	              break;
-  	           case 'I':
-  	              argv[i] = INT2NUM(param.params[i]);
-  	              break;
-  	           default:
-  	              rb_raise(cCallbackError, "Illegal prototype '%c'", a_proto[i]);
+              case 'L':
+                 argv[i] = ULONG2NUM(param.params[i]);
+                 break;
+              case 'P':
+                 if(param.params[i])
+                    argv[i] = rb_str_new2((char *)param.params[i]);
+                 break;
+              case 'I':
+                 argv[i] = INT2NUM(param.params[i]);
+                 break;
+              default:
+                 rb_raise(cAPIProtoError, "Illegal prototype '%s'",
+                    RSTRING(a_proto[i])->ptr
+                 );
             }
         }
-        
+
         v_retval = rb_funcall2(v_proc, rb_intern("call"), argc, argv);
-        
+
         /* Handle true and false explicitly, as some CALLBACK functions
          * require TRUE or FALSE to break out of loops, etc.
          */
-        if(v_retval == Qtrue) 
+        if(v_retval == Qtrue)
            return TRUE;
-        else if(v_retval == Qfalse) 
+        else if(v_retval == Qfalse)
            return FALSE;
-        
+
         switch (*a_return) {
            case 'I':
               return NUM2INT(v_retval);
               break;
            case 'L':
-              return NUM2ULONG(v_retval);    
+              return NUM2ULONG(v_retval);
               break;
            case 'S':
               return (unsigned long)RSTRING(v_retval)->ptr;
               break;
            case 'P':
-	           if(NIL_P(v_retval)){
-	              return 0;
-	           }
-	           else if(FIXNUM_P(v_retval)){
-	              return NUM2ULONG(v_retval);
-	           }
-	           else{
-	              StringValue(v_retval);
-	              rb_str_modify(v_retval);
-	              return (unsigned long)StringValuePtr(v_retval);
-	           }		    
-	           break;
-        }        
+              if(NIL_P(v_retval)){
+                 return 0;
+              }
+              else if(FIXNUM_P(v_retval)){
+                 return NUM2ULONG(v_retval);
+              }
+              else{
+                 StringValue(v_retval);
+                 rb_str_modify(v_retval);
+                 return (unsigned long)StringValuePtr(v_retval);
+              }
+              break;
+        }
     }
-    
+
     return 0;
 }
 
+DWORD CALLBACK CallbackFunction0() {
+   CALLPARAM param = {0};
+   param.params[0] = 0;
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction1(DWORD p1) {
+   CALLPARAM param = {p1};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction2(DWORD p1, DWORD p2){
+   CALLPARAM param = {p1,p2};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction3(DWORD p1, DWORD p2, DWORD p3){
+   CALLPARAM param = {p1,p2,p3};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction4(DWORD p1, DWORD p2, DWORD p3, DWORD p4){
+   CALLPARAM param = {p1,p2,p3,p4};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction5(
+   DWORD p1, DWORD p2, DWORD p3, DWORD p4, DWORD p5
+)
+{
+   CALLPARAM param = {p1,p2,p3,p4,p5};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction6(
+   DWORD p1, DWORD p2, DWORD p3, DWORD p4, DWORD p5, DWORD p6
+)
+{
+   CALLPARAM param = {p1,p2,p3,p4,p5,p6};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction7(
+   DWORD p1, DWORD p2, DWORD p3, DWORD p4, DWORD p5, DWORD p6, DWORD p7)
+{
+   CALLPARAM param = {p1,p2,p3,p4,p5,p6,p7};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction8(
+   DWORD p1, DWORD p2, DWORD p3, DWORD p4,
+   DWORD p5, DWORD p6, DWORD p7, DWORD p8
+)
+{
+   CALLPARAM param = {p1,p2,p3,p4,p5,p6,p7,p8};
+   return CallbackFunction(param);
+}
+
+DWORD CALLBACK CallbackFunction9(
+   DWORD p1, DWORD p2, DWORD p3, DWORD p4, DWORD p5,
+   DWORD p6, DWORD p7, DWORD p8, DWORD p9
+)
+{
+   CALLPARAM param = {p1,p2,p3,p4,p5,p6,p7,p8,p9};
+   return CallbackFunction(param);
+}
+
+void *CallbackTable[] = {
+   CallbackFunction0,
+   CallbackFunction1,
+   CallbackFunction2,
+   CallbackFunction3,
+   CallbackFunction4,
+   CallbackFunction5,
+   CallbackFunction6,
+   CallbackFunction7,
+   CallbackFunction8,
+   CallbackFunction9
+};
+
 /*
  * call-seq:
  *    Win32::API#call(arg1, arg2, ...)
- * 
+ *
  * Calls the function pointer with the given arguments (if any). Note that,
  * while this method will catch some prototype mismatches (raising a TypeError
  * in the process), it is not fulproof.  It is ultimately your job to make
  * sure the arguments match the +prototype+ specified in the constructor.
- * 
+ *
  * For convenience, nil is converted to NULL, true is converted to TRUE (1)
  * and false is converted to FALSE (0).
  */
@@ -564,9 +671,10 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
    Win32API* ptr;
    unsigned long return_value;
    int i = 0;
+   int len;
 
    struct{
-      unsigned long params[16];
+      unsigned long params[20];
    } param;
 
    Data_Get_Struct(self, Win32API, ptr);
@@ -575,7 +683,7 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
 
    v_proto = rb_iv_get(self, "@prototype");
 
-   /* For void prototypes, allow either no args or an explicit nil */
+   // For void prototypes, allow either no args or an explicit nil
    if(RARRAY(v_proto)->len != RARRAY(v_args)->len){
       char* c = StringValuePtr(RARRAY(v_proto)->ptr[0]);
       if(!strcmp(c, "V")){
@@ -589,10 +697,12 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
       }
    }
 
-   for(i = 0; i < RARRAY(v_proto)->len; i++){
+   len = RARRAY(v_proto)->len;
+
+   for(i = 0; i < len; i++){
       v_arg = RARRAY(v_args)->ptr[i];
 
-      /* Convert nil to NULL.  Otherwise convert as appropriate. */
+      // Convert nil to NULL.  Otherwise convert as appropriate.
       if(NIL_P(v_arg))
          param.params[i] = (unsigned long)NULL;
       else if(v_arg == Qtrue)
@@ -619,7 +729,8 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
                break;
             case _T_CALLBACK:
                ActiveCallback = v_arg;
-               param.params[i] = (LPARAM)CallbackFunction;	
+               v_proto = rb_iv_get(ActiveCallback, "@prototype");
+               param.params[i] = (LPARAM)CallbackTable[RSTRING(v_proto)->len];
                break;
             case _T_STRING:
                param.params[i] = (unsigned long)RSTRING(v_arg)->ptr;
@@ -632,6 +743,7 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
    /* Call the function, get the return value */
    return_value = ptr->function(param);
 
+
    /* Return the appropriate type based on the return type specified
     * in the constructor.
     */
@@ -646,13 +758,38 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
          v_return = Qnil;
          break;
       case _T_POINTER:
-         if(!return_value)
+         if(!return_value){
             v_return = Qnil;
-         else
-            v_return = rb_str_new2((TCHAR*)return_value);
+         }
+         else{
+            VALUE v_efunc = rb_iv_get(self, "@effective_function_name");
+            char* efunc = RSTRING(v_efunc)->ptr;
+            if(efunc[strlen(efunc)-1] == 'W'){
+               v_return = rb_str_new(
+                  (TCHAR*)return_value,
+                  wcslen((wchar_t*)return_value)*2
+               );
+            }
+            else{
+               v_return = rb_str_new2((TCHAR*)return_value);
+            }
+         }
          break;
       case _T_STRING:
-         v_return = rb_str_new2((TCHAR*)return_value);
+         {
+            VALUE v_efunc = rb_iv_get(self, "@effective_function_name");
+            char* efunc = RSTRING(v_efunc)->ptr;
+
+            if(efunc[strlen(efunc)-1] == 'W'){
+               v_return = rb_str_new(
+                  (TCHAR*)return_value,
+                  wcslen((wchar_t*)return_value)*2
+               );
+            }
+            else{
+               v_return = rb_str_new2((TCHAR*)return_value);
+            }
+         }
          break;
       default:
          v_return = INT2NUM(0);
@@ -661,35 +798,38 @@ static VALUE api_call(int argc, VALUE* argv, VALUE self){
    return v_return;
 }
 
-/* 
+/*
  * Wraps the Windows API functions in a Ruby interface.
  */
 void Init_api(){
    VALUE mWin32, cAPI, cCallback, cFunction;
-   
+
    /* Modules and Classes */
-   
+
    /* The Win32 module serves as a namespace only */
    mWin32 = rb_define_module("Win32");
-   
+
    /* The API class encapsulates a function pointer to Windows API function */
    cAPI = rb_define_class_under(mWin32, "API", rb_cObject);
-   
-   /* The API::Callback class encapsulates a Windows CALLBACK function */ 
+
+   /* The API::Callback class encapsulates a Windows CALLBACK function */
    cCallback = rb_define_class_under(cAPI, "Callback", rb_cObject);
 
    /* The API::Function class encapsulates a raw function pointer */
    cFunction = rb_define_class_under(cAPI, "Function", cAPI);
-   
-   /* The API::Error class is raised if the constructor fails */
+
+   /* The API::Error class serves as a base class for other errors */
    cAPIError = rb_define_class_under(cAPI, "Error", rb_eRuntimeError);
 
-   /* The API::Callback::Error class is raised if the constructor fails */
-   cCallbackError = rb_define_class_under(cCallback, "Error", rb_eRuntimeError);
+   /* The LoadError class is raised if a function cannot be found or loaded */
+   cAPILoadError = rb_define_class_under(cAPI, "LoadLibraryError", cAPIError);
+
+   /* The PrototypeError class is raised if an invalid prototype is passed */
+   cAPIProtoError = rb_define_class_under(cAPI, "PrototypeError", cAPIError);
 
    /* Miscellaneous */
    rb_define_alloc_func(cAPI, api_allocate);
-   
+
    /* Win32::API Instance Methods */
    rb_define_method(cAPI, "initialize", api_init, -1);
    rb_define_method(cAPI, "call", api_call, -1);
@@ -699,38 +839,39 @@ void Init_api(){
 
    /* Win32::API::Function Instance Methods */
    rb_define_method(cFunction, "initialize", func_init, -1);
-   
+
    /* The name of the DLL that exports the API function */
    rb_define_attr(cAPI, "dll_name", 1, 0);
-   
+
    /* The name of the function passed to the constructor */
    rb_define_attr(cAPI, "function_name", 1, 0);
-   
+
    /* The name of the actual function that is returned by the constructor.
     * For example, if you passed 'GetUserName' to the constructor, then the
     * effective function name would be either 'GetUserNameA' or 'GetUserNameW'.
     */
    rb_define_attr(cAPI, "effective_function_name", 1, 0);
-   
+
    /* The prototype, returned as an array of characters */
    rb_define_attr(cAPI, "prototype", 1, 0);
-   
+
    /* The return type, returned as a single character, S, P, L, I, V or B */
    rb_define_attr(cAPI, "return_type", 1, 0);
-   
+
    /* Win32::API::Callback Instance Methods */
-   
+
    /* The prototype, returned as an array of characters */
    rb_define_attr(cCallback, "prototype", 1, 0);
-      
+
    /* The return type, returned as a single character, S, P, L, I, V or B */
    rb_define_attr(cCallback, "return_type", 1, 0);
 
    /* The numeric address of the function pointer */
+   rb_define_attr(cCallback, "address", 1, 0);
    rb_define_attr(cFunction, "address", 1, 0);
- 
+
    /* Constants */
-   
-   /* 1.2.0: The version of this library, returned as a String */
+
+   /* 1.2.2: The version of this library, returned as a String */
    rb_define_const(cAPI, "VERSION", rb_str_new2(WINDOWS_API_VERSION));
 }

data/test/test_win32_api.rb

@@ -4,6 +4,9 @@
 # Test case for the Win32::API class. You should run this as Rake task,
 # i.e. 'rake test', instead of running it directly.
 ############################################################################
+require 'rubygems'
+gem 'test-unit'
+
 require 'win32/api'
 require 'test/unit'
 include Win32
@@ -11,13 +14,13 @@ include Win32
 class TC_Win32_API < Test::Unit::TestCase
    def setup
       @buf = 0.chr * 260
-      @api = API.new('GetCurrentDirectory', 'LP')
+      @gcd = API.new('GetCurrentDirectory', 'LP')
       @gle = API.new('GetLastError', 'V', 'L')
       @str = API.new('strstr', 'PP', 'P', 'msvcrt')
    end
 
    def test_version
-      assert_equal('1.2.0', API::VERSION)
+      assert_equal('1.3.0', API::VERSION)
    end
 
    def test_constructor_basic
@@ -28,8 +31,8 @@ class TC_Win32_API < Test::Unit::TestCase
    end
  
    def test_call
-      assert_respond_to(@api, :call)
-      assert_nothing_raised{ @api.call(@buf.length, @buf) }
+      assert_respond_to(@gcd, :call)
+      assert_nothing_raised{ @gcd.call(@buf.length, @buf) }
       assert_equal(Dir.pwd.tr('/', "\\"), @buf.strip)
    end
    
@@ -39,78 +42,93 @@ class TC_Win32_API < Test::Unit::TestCase
    end
    
    def test_dll_name
-      assert_respond_to(@api, :dll_name)
-      assert_equal('kernel32', @api.dll_name)
+      assert_respond_to(@gcd, :dll_name)
+      assert_equal('kernel32', @gcd.dll_name)
    end
    
    def test_function_name
-      assert_respond_to(@api, :function_name)
-      assert_equal('GetCurrentDirectory', @api.function_name)
+      assert_respond_to(@gcd, :function_name)
+      assert_equal('GetCurrentDirectory', @gcd.function_name)
       assert_equal('strstr', @str.function_name)
    end
    
-   def test_effective_function_name
-      assert_respond_to(@api, :effective_function_name)
-      assert_equal('GetCurrentDirectoryA', @api.effective_function_name)
+   def test_effective_function_name_default
+      assert_respond_to(@gcd, :effective_function_name)
+      assert_equal('GetCurrentDirectoryA', @gcd.effective_function_name)
       assert_equal('strstr', @str.effective_function_name)
+   end
 
-      @api = API.new('GetCurrentDirectoryA', 'LP')
-      assert_equal('GetCurrentDirectoryA', @api.effective_function_name)
+   def test_effective_function_name_default_explicit_ansi
+      @gcd = API.new('GetCurrentDirectoryA', 'LP')
+      assert_equal('GetCurrentDirectoryA', @gcd.effective_function_name)
+   end
 
-      @api = API.new('GetCurrentDirectoryW', 'LP')
-      assert_equal('GetCurrentDirectoryW', @api.effective_function_name)
+   def test_effective_function_name_default_explicit_wide
+      @gcd = API.new('GetCurrentDirectoryW', 'LP')
+      assert_equal('GetCurrentDirectoryW', @gcd.effective_function_name)
    end
    
    def test_prototype
-      assert_respond_to(@api, :prototype)
-      assert_equal(['L', 'P'], @api.prototype)
+      assert_respond_to(@gcd, :prototype)
+      assert_equal(['L', 'P'], @gcd.prototype)
    end
    
    def test_return_type
-      assert_respond_to(@api, :return_type)
-      assert_equal('L', @api.return_type)
+      assert_respond_to(@gcd, :return_type)
+      assert_equal('L', @gcd.return_type)
    end
    
    def test_constructor_high_iteration
-      1000.times{
-         assert_nothing_raised{ API.new('GetUserName', 'P', 'P', 'advapi32') }
+      assert_nothing_raised{
+         1000.times{ API.new('GetUserName', 'P', 'P', 'advapi32') }
       }
    end
    
    def test_constructor_expected_failures
       assert_raise(ArgumentError){ API.new }
-      assert_raise(API::Error){ API.new('GetUserName', 'PL', 'I', 'foo') }
-      assert_raise(API::Error){ API.new('GetUserName', 'X', 'I', 'kernel32') }
-      assert_raise(API::Error){ API.new('GetUserName', 'PL', 'X', 'kernel32') }
+      assert_raise(ArgumentError){ API.new('GetUserName', ('L' * 21), 'X') }
+      assert_raise(API::LoadLibraryError){ API.new('GetUserName', 'PL', 'I', 'foo') }
+      assert_raise(API::PrototypeError){ API.new('GetUserName', 'X', 'I', 'advapi32') }
+      assert_raise(API::PrototypeError){ API.new('GetUserName', 'PL', 'X', 'advapi32') }
    end
 
-   # Compare MSVCRT error messages vs regular error messages. This validates
-   # that we're skipping the 'A' and 'W' lookups for MSVCRT functions.
    def test_constructor_expected_failure_messages
-      begin
-         API.new('GetBlah')
-      rescue API::Error => err
-         expected = "GetProcAddress() failed for 'GetBlah', 'GetBlahA' and "
-         expected += "'GetBlahW': The specified procedure could not be found."
-         assert_equal(expected, err.to_s)
-      end
+      assert_raise_message("Unable to load function 'Zap', 'ZapA', or 'ZapW'"){
+         API.new('Zap')
+      }
 
-      begin
-         API.new('strxxx', 'P', 'P', 'msvcrt')
-      rescue API::Error => err
-         expected = "GetProcAddress() failed for 'strxxx': The specified "
-         expected += "procedure could not be found."
-         assert_equal(expected, err.to_s)
-      end
+      assert_raise_message("Unable to load function 'strxxx'"){
+         API.new('strxxx', 'P', 'L', 'msvcrt')
+      }
+
+      assert_raise_message("Illegal prototype 'X'"){
+         API.new('GetUserName', 'X', 'I', 'advapi32')
+      }
+
+      assert_raise_message("Illegal return type 'Y'"){
+         API.new('GetUserName', 'PL', 'Y', 'advapi32')
+      }
    end
-   
+
    def test_call_expected_failures
-      assert_raise(TypeError){ @api.call('test', @buf) }
+      assert_raise(TypeError){ @gcd.call('test', @buf) }
    end
-   
+
+   def test_error_classes
+      assert_not_nil(Win32::API::Error)
+      assert_not_nil(Win32::API::LoadLibraryError)
+      assert_not_nil(Win32::API::PrototypeError)
+   end
+
+   def test_error_class_relationships
+      assert_kind_of(RuntimeError, Win32::API::Error.new)
+      assert_kind_of(Win32::API::Error, Win32::API::LoadLibraryError.new)
+      assert_kind_of(Win32::API::Error, Win32::API::PrototypeError.new)
+   end
+
    def teardown
       @buf = nil
-      @api = nil
+      @gcd = nil
       @gle = nil
       @str = nil
    end

data/test/test_win32_api_callback.rb

@@ -4,6 +4,9 @@
 # Test case for the Win32::API::Callback class. You should run this as Rake
 # task, i.e. 'rake test', instead of running it directly.
 ############################################################################
+require 'rubygems'
+gem 'test-unit'
+
 require 'win32/api'
 require 'test/unit'
 include Win32
@@ -33,6 +36,13 @@ class TC_Win32_API_Callback < Test::Unit::TestCase
       assert_respond_to(@callback, :return_type)
       assert_equal('I', @callback.return_type)
    end
+
+   def test_address
+      assert_nothing_raised{ @callback = API::Callback.new('LP', 'I') }
+      assert_respond_to(@callback, :address)
+      assert_kind_of(Fixnum, @callback.address)
+      assert_equal(true, @callback.address > 0)
+   end
    
    def test_callback
       assert_nothing_raised{
@@ -46,7 +56,13 @@ class TC_Win32_API_Callback < Test::Unit::TestCase
    end
    
    def test_constructor_expected_errors
-      assert_raise(API::Callback::Error){ API::Callback.new('X') }
+      assert_raise(API::PrototypeError){ API::Callback.new('X') }
+      assert_raise(API::PrototypeError){ API::Callback.new('L', 'Y') }
+   end
+
+   def test_constructor_expected_error_messages
+      assert_raise_message("Illegal prototype 'X'"){ API::Callback.new('X') }
+      assert_raise_message("Illegal return type 'Y'"){ API::Callback.new('L', 'Y') }
    end
    
    def teardown

data/test/test_win32_api_function.rb

@@ -4,8 +4,12 @@
 # Test case for the Win32::API::Function class. You should run these
 # tests via the 'rake test' task.
 ########################################################################
+require 'rubygems'
+gem 'test-unit'
+
 require 'test/unit'
 require 'win32/api'
+include Win32
 
 class TC_Win32_API_Function < Test::Unit::TestCase
    def setup
@@ -38,8 +42,22 @@ class TC_Win32_API_Function < Test::Unit::TestCase
       assert_equal('L', @func.return_type)
    end
 
-   def test_expected_errors
+   def test_expected_errors_from_arguments
       assert_raise(ArgumentError){ Win32::API::Function.new }
+      assert_raise(TypeError){ Win32::API::Function.new('L') }
+      assert_raise(Win32::API::PrototypeError){ Win32::API::Function.new(1, 'X') }
+      assert_raise(Win32::API::PrototypeError){ Win32::API::Function.new(1, 'X', 'Y') }
+   end
+
+   def test_expected_error_messages
+      assert_raise_message("Illegal prototype 'X'"){ API::Function.new(1, 'X') }
+      assert_raise_message("Illegal return type 'Y'"){ API::Function.new(1, 'L', 'Y') }
+   end
+
+   def test_expected_errors_from_call
+      assert_raise(ArgumentError){ @func.call }
+      assert_raise(ArgumentError){ @func.call(1) }
+      assert_raise(ArgumentError){ @func.call(1, 'a', 2) }
    end
 
    def teardown

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: win32-api
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors: 
 - Daniel J. Berger
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-22 00:00:00 -06:00
+date: 2009-01-04 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -55,7 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: win32utils
-rubygems_version: 1.2.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
 summary: A superior replacement for Win32API