PhMallocUnpack()

Unpack transport data, using a custom memory-allocation function

Synopsis:

char * PhMallocUnpack( PhTransportHdr_t *hdr, 
                       void **ret_struct, 
                       TransportMalloc_t *ymalloc, 
                       void *ymalloc_cb_data );

Library:

ph

Description:

This function unpacks data packed using one of the PhTransport* or PtTransport* functions. Any memory required for the extraction is allocated via calls to the provided ymalloc function. If ymalloc is NULL, a default allocator is used.

The hdr parameter describes the data to be unpacked and is itself extracted from the packed data stream. See PhGetTransportHdr().

The pointer referenced by ret_struct is set to point to the newly unpacked data. The actual data representation of the data extracted is described in the hdr that's passed as the first parameter to this function.

The TransportMalloc_t type (used for the prototype of the ymalloc function) is:

typedef void *TransportMalloc_t( 
                 PhTransportRegEntry_t *trans_entry,
                 void *cbdata,
                 int fixup_index,
                 size_t size );

For each piece of memory that must be allocated while unpacking, the provided ymalloc function is called with the following arguments:

• the transport registry entry for the data being extracted — see PhTransportRegEntry_t
• the provided ymalloc_cb_data
• the index for the data into the fixup array in the transport registry entry
• the number of bytes that must be allocated.

This makes it very easy to unpack specific pieces of data into shared memory blocks, etc.

As the data is unpacked, it's automatically endian-corrected.

To free data unpacked using this function, call PhFreeTransportType().

Returns:

A pointer to the byte in the data stream following the data just extracted.

Classification:

Photon

See also:

PhAllocPackType(), PhFindTransportType(), PhFreeTransportType(), PhPackEntry(), PhRegisterTransportType(), PhTransportRegEntry_t, PhTransportType(), PhUnpack()

Drag and Drop chapter of the Photon Programmer's Guide