PhPackType()

Pack transport data, given the type of data

Synopsis:

char * PhPackType( char *buffer,
                   char const * const type,
                   char const * const desc,
                   int unsigned const grouping_num,
                   int unsigned const handle,
                   int unsigned const request_transport,
                   int unsigned const inlined_transport,
                   char const * const packing_type,
                   void const * const data,
                   int unsigned const size,
                   int unsigned *tot_size,
                   iov_t *iovs,
                   int unsigned *niovs,
                   int unsigned *iovsize );

Library:

ph

Description:

This function takes the data referenced by data and packs it into a stream buffer pointed to by buffer.

You're not likely to call this function directly; call PhTransportType() instead.

The arguments to PhPackType() are:

buffer

A pointer to the buffer in which to pack the data:

• If buffer is NULL, the function simply calculates the size of the buffer required to hold the data. In this case, tot_size, niovs, and iovsize should all be nonNULL.
• If buffer isn't NULL, the function packs the data into the buffer, advancing the current position in the buffer.

type

A descriptive type name, such as image, text, filename, or files. This is simply added to the header for the packed data.

desc

The specifics of what's in the data. The extractor uses a regular-expression match against the description to determine if the data should be unpacked or discarded. This is simply added to the header for the packed data.

grouping_num

When used with Photon's drag and drop mechanism, the grouping_num is used to indicate which stream is just a different representation of other data also packed into the same PhTransportCtrl_t structure. Only one of each grouping_num should be unpacked by the reader/destination.

This value is simply added to the header for the packed data.

handle

A number that you can use to identify a transaction. This is simply added to the header for the packed data.

request_transport

The available transport types that can be specified when requesting data from the source. This can be any of:

• Ph_TRANSPORT_INLINE -- the data being transported is in memory and can be unpacked immediately.
• Ph_TRANSPORT_FILEREF -- the data being transported is in the temporary file(s) named in the inlined data.
• Ph_TRANSPORT_SHMEM -- the data being transported is in the temporary shared object(s) named in the inlined data.
• Ph_TRANSPORT_STREAM -- the data being transported will be inlined a small piece at a time.
• Ph_TRANSPORT_NAMED_STREAM -- the data being transported will be inlined a small piece at a time. The streamed data is named so multiple streams of data can be transferred serially.
• Ph_TRANSPORT_FILE_STREAM -- the contents of files are streamed using extended named streams. This is like the named stream but with extra information with each data block, including file information and so on. The requester of data must choose one of the available request transport types when requesting delivery of additional data.

inlined_transport

The transport type used for the inlined data. This can be one of:

• Ph_TRANSPORT_INLINE -- the data being transported is in memory and can be unpacked immediately.
• Ph_TRANSPORT_FILEREF -- the data being transported is in the temporary file(s) named in the inlined data.
• Ph_TRANSPORT_SHMEM -- the data being transported is in the temporary shared object(s) named in the inlined data.

packing_type

The name of the entry in the transport registry to be used to pack the data. For more information, see PhTransportRegEntry_t. If you already have a pointer to the registry entry, you can call PhPackEntry() instead of PhPackType().

data

A pointer to the data to be packed.

size

The size, in bytes, of the data to be packed. This size is used only for raw data.

tot_size

A pointer to a variable in which to store the total size of the buffer. This should be non-NULL if you're calculating the size required for the buffer (i.e. buffer is NULL).

iovs

a pointer to an array of I/O vectors.

niovs

A pointer to a variable in which to store the number of I/O vectors required. This should be non-NULL if you're calculating the size required for the buffer (i.e. buffer is NULL).

iovsize

A pointer to a variable in which to store the size of the I/O vectors required. This should be non-NULL if you're calculating the size required for the buffer (i.e. buffer is NULL).

Returns:

A pointer to the buffer, or NULL if no data was packed.

Classification:

Photon

See also:

PhAllocPackType(), PhFindTransportType(), PhMallocUnpack(), PhPackEntry(), PhRegisterTransportType(), PhTransportCtrl_t, PhTransportRegEntry_t, PhTransportType(), PhUnpack()

Drag and Drop chapter of the Photon Programmer's Guide