PtTransportType()

Pack transport data

Synopsis:

int PtTransportType(
       PtTransportCtrl_t *ctrl,
       char const * const type,
       char const * const desc,
       int unsigned const grouping_num,
       int unsigned inlined_transport,
       char *packing_type,
       void *vdata,
       int unsigned len,
       int unsigned const flags );

Arguments:

ctrl

A pointer to the PtTransportCtrl_t control structure for the drag-and-drop operation. Multiple data blocks can be packed into the same PtTransportCtrl_t.

This structure must have been created via a call to PtCreateTransportCtrl().

type

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

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

Type	Packing type
image	PhImage
text	string
files	files or PhTransFiles

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

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.

inlined_transport

The transport type to be used for the inlined data. This may 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.
• 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 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.

packing_type

The name of the transport registry entry to be used when packing the data.

vdata

A pointer to the data to be packed inline.

len

The size, in bytes, of the data pointed to by vdata; This argument is only used for packing raw data.

flags

Flags that affect the operation:

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

  ---

  If this bit is set, any modifications to the data that occur between packing and actual transport of the data will be reflected in the data transported.

  ---

Library:

ph

Description:

This function is used to pack inline data for a drag-and-drop operation. It's called by the source widget.

Returns:

0

Success.

-1

The call has failed; errno is set.

Errors:

EINVAL

One of the following occurred:

• One of the parameters was passed incorrectly.
• No transport control was provided.
• No data was provided via vdata.
• No inlined_transport was specified.

ENOENT

No transport registry entry was found for the provided packing_type.

ENOMEM

Not enough memory to pack the provided data.

Classification:

Photon

See also:

PhTransportCtrl_t, PtCreateTransportCtrl(), PtInitDnd(), PtTransportCtrl_t, PtTransportRequestable()

Drag and Drop chapter of the Photon Programmer's Guide