Method: Win::Library#function

Defined in:
lib/win/library.rb

#function(name, params, returns, options = {}, &def_block) ⇒ Object

Defines new method wrappers for Windows API function call:

  • Defines method with original (CamelCase) API function name and original signature (matches MSDN description)

  • Defines method with snake_case name (converted from CamelCase function name) with enhanced API signature When defined snake_case method is called, it converts the arguments you provided into ones required by original API (adding defaults, mute and transitory args as necessary), executes API function call and (optionally) transforms the result before returning it. If a block is attached to method invocation, raw result is yielded to this block before final transformation take place

  • Defines aliases for enhanced method with more Rubyesque names for getters, setters and tests: GetWindowText -> window_text, SetWindowText -> window_text=, IsZoomed -> zoomed?

You may modify default behavior of defined method by providing optional def_block to function definition. If you do so, snake_case method is defined based on your def_block. It receives callable API object for function being defined, arguments and (optional) runtime block with which the method will be called. Results coming from &def_block are then transformed and returned. So, your def_block should specify all the behavior of the method being defined. You can use def_block to:

  • Change original signature of API function, provide argument defaults, check argument types

  • Pack arguments into strings/structs for <in> or <in/out> parameters that expect a pointer

  • Allocate buffers/structs for pointers required by API functions <out> parameters

  • Unpack <out> and <in/out> parameters returned as pointers

  • Explicitly return results of API call that are returned in <out> and <in/out> parameters

  • Convert attached runtime blocks into callback functions and stuff them into <in> callback parameters

  • do other stuff that you think is appropriate to make Windows API function behavior more Ruby-like…

Accepts following options:

:dll

Use this dll instead of default [‘user32’, ‘kernel32’]

:snake_name

Overrides default snake_case method name being defined

:camel_name

Overrides default CamelCase name for function being attached

:camel_only

If true, no snake_case method is defined

:alias(es)

Provides additional alias(es) for defined method

:boolean

Forces method to return true/false instead of nonzero/zero

:fails

Forces method to return nil if function result is equal to following error code

:alternative

Alternative signature for this function



287
288
289
290
291
292
293
294
295
 
# File 'lib/win/library.rb', line 287

def function(name, params, returns, options={}, &def_block)
  snake_name, camel_name, effective_names, aliases = generate_names(name, options)

  api = define_api(name, camel_name, effective_names, params, returns, options)

  define_snake_method(snake_name, aliases, api, options, &def_block) unless options[:camel_only]

  api   # Return api object from function declaration # TODO: Do we even NEED api object?
end