$var is the name of the C variable for a particular funcion argument. $arg is the Perl SV that matches $var. So an "input" typemap sets $var to be some value based on $arg. An "output" typemap sets $arg based on $var. No, I don't recall where that is documented [ other than the source code :( so you might want to read bits of perl/lib/ExtUtils/*.pm from time to time ].

I would not recommend doing C-struct-to-Perl-hash conversion (or vice versa) via a typemap for two reasons:

1. You'd have to do the conversion once or twice per call and the performance penalty can easily be too high.
2. This takes at least a few lines of C code and putting that much C code into a typemap is a pain and hard to maintain.

I find it is better to keep C structs either "packed" into a Perl string if possible, or hidden in a Perl integer if necessary (as far as the XS interface is concerned). The first method is possible if the C code that you are interfacing to allows the caller to allocate the memory for the structs. The second method (or something similar or perhaps lots of memory copying) is required if the C API insists on passing back pointers to memory that it allocated itself.

Then you can write pack/unpack and/or insert/extract routines (in XS and/or Perl) and probably provide one or more Perl wrappers that do the pack-then-call-XS-then-unpack to make things easy for certain cases.

There are a ton of ways to write these pack/unpack and/or insert/extract routines. I'd probably have:

    $packed= mystructPack( \%unpacked );
    $refToUnpacked= mystructUnpack( $packed );
[download]

Also, buffers.h in Win32API::Registry includes some macros for dealing with typemaps of pointers to structs.

int
dx_playf(chdev, fnamep) /* must put tpt here, and am .still. not clear
+ */
    int chdev
    char *fnamep
    PREINIT:
        DV_TPT tptmp[2];
    CODE:
    /* Will the constants below be worked out of the
       headers, which are included above in the XS?
       I've seen lots of ways of getting them to Perl,
       but perl does not need them */
       tpt[0].tp_type   = IO_CONT;    /* the next entry is next on arr
+ay */
       tpt[0].tp_termno = DX_IDDTIME; /* Interdigit Delay */
       tpt[0].tp_length = 2;
       tpt[0].tp_flags = TF_IDDTIME;

       tpt[1].tp_type   = IO_EOT; /* last entry */
       tpt[1].tp_termno = DX_MAXDTMF; /* Maximum digits to get from ca
+ller */
       tpt[1].tp_length = 1;
       tpt[1].tp_flags = TF_MAXDTMF;

        RETVAL = dx_playf(chdev, fnamep, tptmp, 0);
    OUTPUT:
        RETVAL
[download]

typedef struct DV_TPT {
           unsigned short   tp_type;             /* Flags describing t
+his entry */
           unsigned short   tp_termno;           /* Termination Parame
+ter number */
           unsigned short   tp_length;           /* Length of terminat
+or */
           unsigned short   tp_flags;            /* Parameter attribut
+e flag */
           unsigned short   tp_data;             /* Optional additiona
+l data */
           unsigned short   rfu;                 /* Reserved          
+       */
           DV_TPT           *tp_nextp;           /* Pointer to next te
+rmination TPT */
}DV_TPT;
[download]

int
dx_open(chdev, mode)
    const char * chdev
    int mode

int
dx_close(dev)
    int dev

int
dx_sethook(chdev, hookstate, mode)
    int chdev
    int hookstate
    unsigned short mode
[download]

$chdev = Starla::dx::dx_open("dxxxB1C1",0)  or die "Cannot open dxxxB1
+C1 ($!)\n";
print "Device is $chdev ($!), state is ";
$tmp = Starla::dx::ATDX_STATE($chdev);
print "$tmp ($!)\n";
[download]