define_c_proc

Definition: integer rid = define_c_proc(object lib, object fname, sequence args)
Description: Define the characteristics of a C function that you wish to call as a procedure from your Phix program. A small integer, known as a routine id , will be returned, or -1 if the function cannot be found.

The define_cffi_proc routine is a string-based wrapper of this routine, which you may find easier to use.

lib is an address returned by open_dll(), or {}.
if lib is an atom, fname is the name of a function within that dll, optionally as either {'+',"name"} or "+name" to specify the CDECL calling convention.
if lib is {}, fname is the (atom) address of a machine code function, optionally as {'+',addr} to specify the CDECL calling convention.

CDECL is the default/only calling convention on a Linux system.
STDCALL is the default in a Windows system.
The CDECL convention requires the callee to clean up the stack, and is therefore more suited to variable numbers of arguments, whereas with STDCALL the routine cleans up the stack before returning.

args is a list of the parameter types for the routine. A list of C types is contained in dll.e , and define_c_func.
Comments: The routine id , rid, can be passed to c_proc(), when you want to call the C function.

You can pass any C integer type or pointer type. You can also pass a phix atom as a C double or float.

In C (on Windows and Linux), parameter types which use 4 bytes or less are all passed the same way, so it is not necessary to be exact.

Currently, there is no way to pass a C structure by value. You can only pass a pointer to a structure.

The C function can return a value but it will be ignored. If you want to use the value returned by the C function, you must instead define it with define_c_func() and call it with c_func().
Example:
atom user32
integer ShowWindow
-- open user32.dll - it contains the ShowWindow C function
user32 = open_dll("user32.dll")
-- It has 2 parameters that are both C int.
ShowWindow = define_c_proc(user32, "ShowWindow", {C_INT, C_INT})
if ShowWindow=-1 then
    puts(1, "ShowWindow not found!\n")
end if
See Also: c_proc, define_cffi_proc, define_c_func, c_func, open_dll, Calling C Functions