PhTransportType()

Pack data into a PhTransportCtrl_t structure

Synopsis:

PhTransportLink_t *
   PhTransportType( 
      PhTransportCtrl_t *ctrl, 
      char const * const type,
      char const * const desc, 
      int unsigned const grouping_num, 
      int unsigned const handle,
      int unsigned inlined_transport,
      char *packing_type,
      void *vdata,
      int unsigned len,
      int unsigned const flags );

Library:

ph

Description:

This function takes the data referenced by vdata and packs it into a stream buffer within the provided PhTransportCtrl_t structure pointed to by ctrl.

The data is packed using the transport registry entry that matches packing_type. For more information, see PhTransportRegEntry_t.

The provided type, desc, grouping_num, and handle are added to the packed data's header information.

The PhTransportCtrl_t structure pointed to by ctrl was created via a call to PhCreateTransportCtrl(). The len parameter is used only for packing raw data.

The inlined_transport argument indicates the transport type used for the inlined data, and 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.

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

The type should be a descriptive type name, such as image, text, filename, or files.

Each type has its most common and expected packing_type associated with it. For example:

Type Packing type
image PhImage
text string
files files or PhTransFiles

Other packing types can be used, but there's no guarantee that the reader/recipient of the data will be expecting the type of data packed. In this case, the data is ignored.

The desc should detail the specifics of what is in the data. The extractor uses a regular expression match against the description to determine if the data should be unpacked or discarded.

The flags parameter has the following valid bits:

Ph_DONT_COPY
Refer to the data to be transported instead of physically copying the data to the transport control's stream buffers.

Note: If this flag is used, any modifications to the data that occur between packing and actual transport of the data will be reflected in the data transported.

Returns:

A pointer to a PhTransportLink_t structure (within the transport control's stream buffer list) that contains the packed data, or NULL if the call has failed (errno is set).

Errors:

EINVAL
One of the following occurred:
ENOENT
No transport registry entry was found for the provided packing_type.
ENOMEM
There wasn't enough memory to pack the provided data.

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PhAllocPackType(), PhFindTransportType(), PhFreeTransportType(), PhMallocUnpack(), PhPackEntry(), PhRegisterTransportType(), PhTransportCtrl_t, PhTransportLink_t, PhTransportRegEntry_t, PhUnpack(), PtCreateTransportCtrl(), PtDndFetch_t, PtDndSelect(), PtTransportType()

Drag and Drop chapter of the Photon Programmer's Guide