ctypes

The ctypes object contains methods and predefined data types used to create and manage a library.

Method overview

Properties

Constants

ABI constants

These constants are used to specify the ABI used to call a native function in the library.

Predefined data types

Primitive types

These types behave the same on all platforms.

Types that act like specific C types

These types are designed to work exactly like the corresponding type on the native platform.

Character types

Character types are 8-bit values that behave like their C counterparts. They're similar to the int8_t and uint8_t types, except conversion is handled differently.

For example, ctypes.char.array(30)(str) converts the string str to UTF-8 and returns a new CData object of array type.

Types whose size varies depending on platform

Because it's unknown whether these values will be 32-bit or 64-bit, they are not automatically converted into JavaScript numbers. Instead, these convert into ctypes.Int64 or ctypes.UInt64 JavaScript objects; see 64-bit integers for details.

JavaScript characters

16-bit C Unicode characters are handled by js-ctypes using the jschar type.

Special C types

These types represent C types that have special meanings.

Large integer types

Because JavaScript doesn't support large (64-bit) integers, js-ctypes provides two data types allowing access to 64-bit integer data.

Methods

cast()

Casts the specified CData object to a new type, returning a new CData object representing the value in the new type. See Type casting for details.

CData cast(
  data,
  type
);

Parameters

data

The CData object to type cast.

type

The type to which to cast the value. This can be one of the Predefined data types, or any user-defined types.

Return value

A new CData object representing the same data, but with the specified type.

libraryName()

Returns the correct platform-specific filename for a given library name (e.g. libnss3.dylib for nss3 on OS X.)

String libraryName(
  name
);

Parameters

name

The name of the library.

Return value

String containing the platform-specific filename of the library.

open()

Opens a library, specified by a pathname. The library is loaded from the specified full path, or, if a partial path is specified, from the appropriate library directory based on the platform on which the application is running. See Library search paths for more details.

Library open(
  libSpec
);

Parameters

libSpec

The native library to open, specified as a pathname string.

Return value

A Library object representing the opened library.

Examples

Example of StructType() on Windows

Let's say we need TB_BUTTON, this type needs to be created. So we look up on MSDN what the TB_BUTTON structures is (MSDN :: TB_BUTTON Structure) and it says it is:

typedef struct {
  int       iBitmap;
  int       idCommand;
  BYTE      fsState;
  BYTE      fsStyle;
#ifdef _WIN64
  BYTE      bReserved[6];
#else
#if defined(_WIN32)
  BYTE      bReserved[2];
#endif
#endif
  DWORD_PTR dwData;
  INT_PTR   iString;
} TBBUTTON, *PTBBUTTON, *LPTBBUTTON;

So now notice that if it's 64-bit process it's different than if it's 32-bit process. So we will figure that out and create the structure appropriately. This is what the final looks like:

var struct_TBButton;
if (ctypes.voidptr_t.size == 4 /* 32-bit */) {
  struct_TBButton = ctypes.StructType('TBButton', [
    {'iBitmap': ctypes.int},
    {'idCommand': ctypes.int},
    {'fbState': ctypes.unsigned_char},
    {'fsStyle': ctypes.unsigned_char},
    {'bReserved': ctypes.unsigned_char},
    {'bReserved2': ctypes.unsigned_char},
    {'dwData': ctypes.uintptr_t},
    {'iString': ctypes.intptr_t}
  ]);
}
else if (ctypes.voidptr_t.size == 8 /* 64-bit */) {
  struct_TBButton = ctypes.StructType('TBButton', [
    {'iBitmap': ctypes.int},
    {'idCommand': ctypes.int},
    {'fbState': ctypes.unsigned_char},
    {'fsStyle': ctypes.unsigned_char},
    {'bReserved': ctypes.unsigned_char},
    {'bReserved2': ctypes.unsigned_char},
    {'bReserved3': ctypes.unsigned_char},
    {'bReserved4': ctypes.unsigned_char},
    {'bReserved5': ctypes.unsigned_char},
    {'bReserved6': ctypes.unsigned_char},
    {'dwData': ctypes.uintptr_t},
    {'iString': ctypes.intptr_t}
  ]);
}
else {
  throw new Error("wut?!");
}

console.log(struct_TBButton.size);
// 20 on 32-bit, 32 on 64-bit if I'm not mistaken

There is another way to do this, we can use ArrayType, but example for this I don't know at this time.

Credit for this example is to nmaier (StackOverflow :: Getting TB_BUTTON is crashing and not working)

Example of cast and FunctionType on Windows

Components.utils.import("resource://gre/modules/ctypes.jsm");

var kernel = ctypes.open("kernel32.dll");
var HMODULE = ctypes.uint32_t;
var HWND = ctypes.uint32_t;
var LPCTSTR = ctypes.jschar.ptr;
var LPCSTR = ctypes.char.ptr;
var LoadLibrary = kernel.declare("LoadLibraryW", ctypes.winapi_abi, HMODULE, LPCTSTR);
var GetProcAddress = kernel.declare("GetProcAddress", ctypes.winapi_abi, ctypes.void_t.ptr, HMODULE, LPCSTR);

var hUser = LoadLibrary("user32");
var funcPtr = GetProcAddress(hUser, "MessageBoxW");

// Now we have a pointer to a function, let's cast it to the right type
var MessageBoxType = ctypes.FunctionType(ctypes.winapi_abi, ctypes.int32_t, [HWND, LPCTSTR, LPCTSTR, ctypes.uint32_t]);
funcPtr = ctypes.cast(funcPtr, MessageBoxType.ptr);
funcPtr(0, "Test1", "Test2", 0);

Credit for this example is to Wladimir Palant (StackOverflow :: How to call a function using pointer in js-ctypes)

See also

• ctypes.jsm
• Using js-ctypes
• ArrayType
• FunctionType
• PointerType
• StructType
• Int64
• UInt64
• ABI
• Library