NAME

FFI::C::Def - Data definition for FFI

VERSION

version 0.15

SYNOPSIS

In your C code:

#include <stdint.h>
#include <stdio.h>

typedef struct {
  uint8_t red;
  uint8_t green;
  uint8_t blue;
} color_t;

void
print_color(color_t *c)
{
  printf("[%02x %02x %02x]\n",
    c->red,
    c->green,
    c->blue
  );
}

In your Perl code:

use FFI::Platypus 1.00;
use FFI::C::StructDef;

my $ffi = FFI::Platypus->new( api => 1 );
# See FFI::Platypus::Bundle for how bundle works.
$ffi->bundle;

my $def = FFI::C::StructDef->new(
  $ffi,
  name  => 'color_t',
  class => 'Color',
  members => [
    red   => 'uint8',
    green => 'uint8',
    blue  => 'uint8',
  ],
);

my $red = Color->new({ red => 255 });

my $green = Color->new({ green => 255 });

$ffi->attach( print_color => ['color_t'] );

print_color($red);   # [ff 00 00]
print_color($green); # [00 ff 00]

# that red is a tad bright!
$red->red( 200 );

print_color($red);   # [c8 00 00]

DESCRIPTION

This class is the base class for all def classes in the FFI::C collection. The def classes are for defining C struct, union and array types that can be used from Perl and passed to C via FFI::Platypus.

You don't create an instance of this class directly, rather one of the subclasses: FFI::C::StructDef, FFI::C::UnionDef, FFI::C::ArrayDef.

CONSTRUCTOR

new

my $def = FFI::C::StructDef->new(%opts);
my $def = FFI::C::StructDef->new($ffi, %opts);
my $def = FFI::C::UnionDef->new(%opts);
my $def = FFI::C::UnionDef->new($ffi, %opts);
my $def = FFI::C::ArrayDef->new(%opts);
my $def = FFI::C::ArrayDef->new($ffi, %opts);

The constructor for this class shouldn't be invoked directly. If you try and exception will be thrown.

For subclasses, the first argument should be the FFI::Platypus instance that you want to use with the def. If you do not provide it, then one will be created internally for you. All def classes accept these standard options:

name

The FFI::Platypus alias for this def. This name can be used in function signatures when creating or attaching functions in FFI::Platypus.

class

The Perl class for this def. The Perl class can be used to create an instance of this def instead of invoking the create method below.

members

This is an array reference, which specifies the member fields for the def. How exactly it works depends on the subclass, so see the documentation for the specific def class that you are using.

nullable

If true, then the type can be undef when passed into C. undef will be translated to NULL.

METHODS

ffi

my $ffi = $def->ffi;

Returns the FFI::Platypus instance used by this def.

name

my $name = $def->name;

Return the FFI::Platypus alias for this def. This name can be used in function signatures when creating or attaching functions in FFI::Platypus.

class

my $class = $def->class;

Returns the Perl class for this def, if one was specified. The Perl class can be used to create an instance of this def instead of invoking the create method below.

size

my $size = $def->size;

Returns the size of the def in bytes.

align

my $align = $def->align;

Returns the alignment in bytes of the def.

nullable

my $bool = $def->nullable;

Returns true if undef is allowed to be passed in to C functions. undef will be translated to NULL.

create

my $instance = $def->create;
my $instance = $def->class->new;  # if class was specified

Creates an instance of the def.

SEE ALSO

FFI::C

FFI::C::Array

FFI::C::ArrayDef

FFI::C::Def

FFI::C::File

FFI::C::PosixFile

FFI::C::Struct

FFI::C::StructDef

FFI::C::Union

FFI::C::UnionDef

FFI::C::Util

FFI::Platypus::Record

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm FFI::C

perl -MCPAN -e shell
install FFI::C