Aprendendo sobre Win32API

O que é uma API (Application Programming Interface - Interface de Programação de Aplicativos)?
São blocos de DLL's usados para gerenciar suas principais funções (funções da DLL), e elas nos darão a chave para controlar tudo (da DLL). No caso, as mais usadas são a Win32API e a Win32OLE. Como o RGSS só dá suporte à Win32API, então iremos falar dela.

Win32API: É um conjunto base de API para o SO do Windows.

Chamar uma API é basicamente chamar uma DLL, definir a função que irá ser usada, os tipos de parâmetros e o valor dos seus parâmetros. Nisso tudo irá haver o retorno de um objeto.

A classe Win32API tem 4 argumentos essenciais que precisam ser definidos. Veja abaixo:

Código:

Win32API.new(name, function, imputArray, export)

name: Neste argumento, iremos definir o nome da DLL que irá ser chamada. Por exemplo, a DLL "user32" que fica dentro da pasta "C:\Windows\system32\".
O tipo do valor desse argumento deve ser uma String (Texto).

function: Neste argumento, iremos definir o nome da função que será chamada. Por exemplo, a função Beep da DLL "kernel32".
O tipo do valor desse argumento deve ser uma String (Texto).

imputArray: Trata-se de um conjuntos de letras (string) que irá definir os parâmetros que serão usados para iniciar a function. Existem, pelo menos, 5 letras em questão (n, l, i, p, v), mais abaixo você verá o que cada letra significa.

export: Neste argumento, definimos o valor do parâmetro que determina o valor do parâmetro em resposta da determinada function. É bem simples a lógica em si. Exemplo: Suponhamos que você chama uma DLL, você determina a sua função e a função da DLL que irá ser chamada irá desenhar um quadrado na tela. Como que o RGSS irá identificar que você clicou no quadrado? A resposta é através do export. Se no caso a função retornar o valor de uma String (Texto), você irá definir o export como "p" e assim por diante.


n(Long) ou l(Long): Representa números não literais.
i(Integer): Representa o integers (números inteiros, bignums, fixnums)
p(String): Representa uma String (texto).
v(Void): Representa o valor nulo (nil).


Agora, iremos chamar nossa primeira DLL, será algo bem simples. Chamaremos a DLL "kernel32", a função será o Beep — Usado para gerar tons simples. Veja abaixo todo o código e, logo após, as suas explicações e como achá-los.

Código:

beep = Win32API.new("kernel32.dll", "Beep", "LL", "L")
beep.call(0x7FFF, 50)

Primeiro passo: O primeiro passo é descobrir qual DLL está sendo usada. No caso acima, é a DLL "kernel32"

Segundo passo: É saber qual função está sendo chamada da DLL. No caso acima, é a função do Beep (que é usado para gerar tons simples.)
Obs.: Há sites específicos que mostram as funções de algumas DLLs, como, por exemplo, o site AllAPI.

Terceiro passo: É saber os parâmetros da imputArray. E como irei saber os benditos parâmetros da imputArray? Existem sites de buscas que mostram, de forma detalhada, as funções da DLL, como o MSDN da própria Microsoft. Bom, como estamos chamando a DLL "kernel32" e sua função "Beep", vamos usar o site de busca AllAPI. Vamos por partes.
Entrando no site, você verá uma coluna de cor verde, e nessa coluna terá a opção API List, clique lá. Após o clique, irá aparecer um index com as letras do alfabeto, logo abaixo do index, há algumas funções de várias DLLs do Windows (a maioria são da "user32" e do "kernel32"). Como estamos procurando a função Beep, clique no index B. Após o clique, irá aparecer abaixo a função Beep, clique nela.

Após o clique, irá aparecer uma nova página contendo a descrição da função, a DLL que a pertence, os parâmetros do imputArray e o valor do parâmetro do export. Veja abaixo mais detalhadamente:

Vermelho e Verde: Aqui é o nome da função da DLL. No caso, é o Beep.
Azul: Aqui é o nome da DLL. No caso, é a kernel32.
Roxo escuro: Aqui ficam os parâmetros do imputArray. No caso, seria "LL".
Rosa: Aqui fica o parâmetro do export. No caso, seria "L".
Abaixo há uma tradução do quadrinho cinza para que vocês entendam melhor.
Chamar função Beep da DLL "kernel32" (valor do imputArray dwFreq é Long(L), valor do imputArray dwDuration é Long(L)) valor do export é Long(L).
Daí podemos concluir que o nome da DLL é "kernel32", a sua função é "Beep", o parâmetro do imputArray é "LL" e o parâmetro do export é "L".

Código:

beep = Win32API.new("kernel32.dll", "Beep", "LL", "L")
beep.call(0x7FFF, 50)

Ok, mas, em relação ao comando call, como poderei saber os valores do comando? Logo mais abaixo na página do site, haverá um tópico chamado Parameter Information, lá terá uma explicação dos argumentos que serão estabelecidos no call. No caso, é o dwFreq e o dwDuration. Dois argumentos que precisam ser definidos na chamada da função Beep.

Código:

beep.call(dwFreq, dwDuration)

dwFreq: Como está escrito no site, é o valor específico da frequência em hertz, do som. Este parâmetro deve estar na gama de 37 a 32.765 (0x25 ... 0x7FFF) .
dwDuration: Como está escrito no site, é o valor específico da duração em milissegundos do som.
Com isso, podemos saber os argumentos a serem definidos. Vejamos abaixo um código exemplo: O sonzinho é meio sinistro, mas tá valendo.

Código:

dwDuration = 50
beep = Win32API.new("kernel32.dll", "Beep", "LL", "L")
(5000...5050).each { |dwFreq|
beep.call(dwFreq, dwDuration)
}

Bom, chegamos ao final da aula. Recomendo agora vocês tentem chamar novas funções, descobrir novas coisas usando o Win32API. Agora é com vocês!

Tópico original:
http://tutorial-dax.weebly.com/win32api.html

Uma correção do tópico em relação as parâmetros passados na função e como funciona a definição de tipos. Onde classificou com n, l, i, p e v existem outros. Esses argumentos são especificados pelo tipo assim como na função pack (para arrays). Na documentação do Ruby 1.8.6 (versão mais próxima da usada no RMXP com documentação oficial disponível), vemos o seguinte:

Código:

Directive    Meaning
---------------------------------------------------------------
    @     |  Moves to absolute position
    A     |  ASCII string (space padded, count is width)
    a     |  ASCII string (null padded, count is width)
    B     |  Bit string (descending bit order)
    b     |  Bit string (ascending bit order)
    C     |  Unsigned char
    c     |  Char
    D, d  |  Double-precision float, native format
    E     |  Double-precision float, little-endian byte order
    e     |  Single-precision float, little-endian byte order
    F, f  |  Single-precision float, native format
    G     |  Double-precision float, network (big-endian) byte order
    g     |  Single-precision float, network (big-endian) byte order
    H     |  Hex string (high nibble first)
    h     |  Hex string (low nibble first)
    I     |  Unsigned integer
    i     |  Integer
    L     |  Unsigned long
    l     |  Long
    M     |  Quoted printable, MIME encoding (see RFC2045)
    m     |  Base64 encoded string
    N     |  Long, network (big-endian) byte order
    n     |  Short, network (big-endian) byte-order
    P     |  Pointer to a structure (lammer-length string)
    p     |  Pointer to a null-terminated string
    Q, q  |  64-bit number
    S     |  Unsigned short
    s     |  Short
    U     |  UTF-8
    u     |  UU-encoded string
    V     |  Long, little-endian byte order
    v     |  Short, little-endian byte order
    w     |  BER-compressed integer\fnm
    X     |  Back up a byte
    x     |  Null byte
    Z     |  Same as ``a'', except that null is added with *

Fonte: http://ruby-doc.org/core-1.8.6/Array.html#method-i-pack

Paulo S. escreveu:Uma correção do tópico em relação as parâmetros passados na função e como funciona a definição de tipos. Onde classificou com n, l, i, p e v existem outros. Esses argumentos são especificados pelo tipo assim como na função pack (para arrays). Na documentação do Ruby 1.8.6 (versão mais próxima da usada no RMXP com documentação oficial disponível), vemos o seguinte:

Código:

Directive    Meaning
---------------------------------------------------------------
    @     |  Moves to absolute position
    A     |  ASCII string (space padded, count is width)
    a     |  ASCII string (null padded, count is width)
    B     |  Bit string (descending bit order)
    b     |  Bit string (ascending bit order)
    C     |  Unsigned char
    c     |  Char
    D, d  |  Double-precision float, native format
    E     |  Double-precision float, little-endian byte order
    e     |  Single-precision float, little-endian byte order
    F, f  |  Single-precision float, native format
    G     |  Double-precision float, network (big-endian) byte order
    g     |  Single-precision float, network (big-endian) byte order
    H     |  Hex string (high nibble first)
    h     |  Hex string (low nibble first)
    I     |  Unsigned integer
    i     |  Integer
    L     |  Unsigned long
    l     |  Long
    M     |  Quoted printable, MIME encoding (see RFC2045)
    m     |  Base64 encoded string
    N     |  Long, network (big-endian) byte order
    n     |  Short, network (big-endian) byte-order
    P     |  Pointer to a structure (lammer-length string)
    p     |  Pointer to a null-terminated string
    Q, q  |  64-bit number
    S     |  Unsigned short
    s     |  Short
    U     |  UTF-8
    u     |  UU-encoded string
    V     |  Long, little-endian byte order
    v     |  Short, little-endian byte order
    w     |  BER-compressed integer\fnm
    X     |  Back up a byte
    x     |  Null byte
    Z     |  Same as ``a'', except that null is added with *

Fonte: http://ruby-doc.org/core-1.8.6/Array.html#method-i-pack

Bem lembrado, Soreto.

+ 1 crédito.

Eu geralmente uso só esses do tópico mesmo, mas é sempre bom ficar atento.