Class Windows::API
In: lib/windows/api.rb
Parent: Object

Methods

Classes and Modules

Class Windows::API::Error

Constants

VERSION = '0.2.0'

Attributes

dll_name  [R] 
function_name  [R] 
prototype  [R] 
return_type  [R] 

Public Class methods

Returns the value of the @auto_constant class instance variable. The default is nil, i.e. none. See the Windows::API.auto_constant= documentation for more information.

Automatically sets a constant to match the function name.

The standard practice for defining Windows::API objects is to use a constant that matches the function name. For example, this is a typical idiom:

   module Windows
      module File
         GetFileAttributes = API.new('GetFileAttributes', 'P','L')
      end
   end

With the API.auto_constant value set to true you can avoid the assignment step and the matching constant name will be automatically set for you in the namespace defined in API.auto_namespace. In other words, this example is identical to the one above:

   module Windows
      module File
         API.auto_constant  = true
         API.auto_namespace = 'Windows::File'
         API.new('GetFileAttributes', 'P', 'L')
      end
   end

If the auto_constant class variable is set to true, but no auto_namespace is set, an error will be raised. Note that the namespace must refer to an existing module (not a class).

Returns the value of the auto_method class instance variable. Used in conjunction with auto_unicode. See API.auto_method= for more information.

If this option is set to true then a corresponding method is automatically generated when you create a new Windows::API object.

For example, instead of doing this:

   module Windows
      module File
         GetFileAttributes = API.new('GetFileAttributes', 'P', 'L')

         def GetFileAttributes(x)
            GetFileAttributes.call(x)
         end
      end
   end

You can do this, and have the method autogenerated for you.

   module Windows
      module File
         API.auto_namespace = 'Windows::File'
         API.auto_constant  = true
         API.auto_method    = true
         GetFileAttributes  = API.new('GetFileAttributes', 'P', 'L')
      end
   end

If the Windows::API object is declared to be a boolean in the constructor, then the method definition automatically includes a ’!= 0’ clause at the end of the call. That way, you can do ‘if SomeMethod(x)’ instead of having to do ‘if SomeMethod(x) != 0’, and it will do the right thing.

If the API.auto_unicode option is also set to true, then you will get three method definitions. The standard function name, the explicit ANSI (‘A’) version and the explicit Unicode/wide version (‘W’). The exception to this rule is that the explicit ANSI and Unicode methods will NOT be generated if the function passed to the constructor already ends with ‘A’ or ‘W’.

Returns the value of the auto_namespace class instance variable. Used in conjunction with API.auto_constant and/or API.auto_method.

Sets the value of the auto_namespace class nstance variable. The default is nil, i.e. none. Use in conjunction with the auto_constant and/or auto_method class variables, this method will automatically set a constant and/or method in namespace equal to the function name set in the constructor.

The namespace must refer to an existing module, not a class.

Returns the value of the auto_unicode class instance variable. This is used in conjunction with the auto_method and/or auto_constant class variables. Not significant if neither of those variables are set.

If set to true, and the auto_constant variable is set, then the automatic constant generation will generate the explicit ANSI (‘A’) and Unicode/wide (‘W’) versions of the function passed to the constructor, if such versions exist. Likewise, if the the auto_method variable is set, then explicit ANSI and Unicode methods are generated.

Here‘s a typical idiom:

module Windows

   module Path
      API.auto_namespace = Windows::Path
      API.auto_constant = true
      API.new('shlwapi', 'PathAddBackslash', 'P', 'P')
      API.new('shlwapi', 'PathAddBackslashA', 'P', 'P')
      API.new('shlwapi', 'PathAddBackslashW', 'P', 'P')
   end

end

That can be reduced to this:

module Windows

   module Path
      API.auto_namespace = Windows::Path
      API.auto_constant = true
      API.auto_unicode  = true
      API.new('shlwapi', 'PathAddBackslash', 'P', 'P')
   end

end

This value is ignored if the function passed to the constructor already ends with an ‘A’ or ‘W’.

Creates and returns a new Windows::API object. The func is the name of the Windows function.

The proto is the function prototype for func. This can be a string or an array of characters. The possible valid characters are ‘I’ (integer), ‘B’ (BOOL), ‘L’ (long), ‘V’ (void), or ‘P’ (pointer). The default is void (‘V’).

The rtype argument is the return type for the function. The valid characters are the same as for the proto. The default is long (‘L’).

The ‘B’ (BOOL) return type is the same as ‘I’ (Integer). This is significant only if the API.auto_method option is set to true, in which case it alters the generated method definition slightly. See the API.auto_method= class method for more information.

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

Public Instance methods

Calls the function name set in the constructor.

[Validate]