PtTransportRequestable()

Add an entry for requestable data to the drag-and-drop data

Synopsis:

PtRequestables_t *
   PtTransportRequestable(
      PtTransportCtrl_t *ctrl,
      char const * const type,
      char const * const desc,
      int unsigned const flags,
      int unsigned transport,
      PtTransportReqDataCB_t *rq_callback,
      void *rq_callback_data );

Arguments:

ctrl

A pointer to the PtTransportCtrl_t control structure for the drag-and-drop operation.

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.

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.

  ---

transport

The available transport types that can be specified when requesting data from the source:

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. The requester of data must choose one of the available request transport types when requesting delivery of additional data.

rq_callback

A pointer (of type PtTransportReqDataCB_t *) to the callback routine that will provide the data if the destination of the drag-and-drop operation asks for requestable data. For more information, see below.

This can be NULL if the source widget calls PtAddResponseType() to pack the requestable data before initiating the drag-and-drop operation.

rq_callback_data

A pointer to arbitrary data for the rq_callback function. This pointer is stored in the rq_callback_data member of the PtRequestables_t structure that's passed to the callback.

Library:

ph

Description:

This function adds an entry for requestable data to the data being packed up for a drag-and-drop operation. It's called by the source widget when it's starting the operation.

Request callback function

The callback function specified by the rq_callback argument has the following prototype:

int unsigned rq_callback ( int unsigned type,
                           PtReqResponseHdr_t *req_hdr,
                           PtRequestables_t *requestables );

The arguments are:

type

Currently, this is Pt_DND_REQUEST_DATA, which indicates that data is being requested.

req_hdr

A pointer to a PtReqResponseHdr_t structure that provides useful information and tracks streams; see below.

requestables

A pointer to a description of the requestable type. The callback should use this when it calls PtAddResponseType().

The callback function should return:

Pt_CONTINUE

The data has been or will be provided.

Pt_END

The source is canceling the destination's request.

PtReqResponseHdr_t structure

The PtReqResponseHdr_t data structure determines how a data request is responded to. It's defined as:

typedef struct req_resp_msg_hdr PtReqResponseHdr_t;

struct req_resp_msg_hdr {
    int unsigned    transport;
    int unsigned    cmd;
    int unsigned    chunk_size;
    int             total_size;
    int unsigned    byte_offset;
    void *          source_handle;
    void *          dest_handle;
    int unsigned    data_size;
    };

This structure's members can be used in the callback function as described below:

transport

If the Ph_TRANSPORT_ENDIAN_OK bit is set in this member, then the source and destination are of the same endianness. For example:

if (! (req_hdr->transport &
       Ph_TRANSPORT_ENDIAN_OK))
   // Destination is a different endian
  

cmd

The action to take. If the callback's type argument is Pt_DND_REQUEST_DATA, cmd is Pt_DND_CMD_PROVIDE_DATA.

chunk_size

The size of the data that the client will accept. If this is too small, return Pt_END from the callback to make the request fail.

total_size

The size of data to be sent to the destination. This is equal to chunk_size if you're not streaming.

byte_offset

The offset into the data from which to start sending data. This is useful for streams of data.

source_handle

An identifier for the source that's passed back in this member if more than one transmission is required to provide the requested data. The destination shouldn't modify this member.

dest_handle

An identifier for the destination that's passed back in this member if more than one transmission is required to provide the requested data. The source shouldn't modify this member.

data_size

If you're responding with packed data, this is the packed size, not the unpacked size.

Returns:

0

Success.

-1

An error occurred; errno is set.

Classification:

Photon

See also:

PtAddResponseType(), PtCreateTransportCtrl(), PtInitDnd(), PtTransportCtrl_t, PtTransportType()

Drag and Drop chapter of the Photon Programmer's Guide