The parameters are:
listObject The transfer list object indicated by pArgs.
ids An array of transfer types that you support.
idsLen The number of transfer types in the ids arr~y.
CHAPTER 83 I TRANSFER CLASS 173 Performing One-Shot Transfers
The function sends msgListAddltem to the list for each transfer type in the array.
Remember that the order of the transfer types in ids is important. XferAddldsO adds the transfer types to the end of the list object as they appear in ids.
Mter adding your transf~r types to the list, you must send it to your ancestor.
When msgXferList returns from your ancestor, the transfer list object contains the transfer types supported by your class and all your ancestors. At this point you can return from msgXferList.
Searching a Transfer Type List
When the sender and its ancestors return msgXferList, the XferMatchO function calls XferListSearchO, which searches the transfer list returned by msgXferList, looking for a transfer type that matches one in an array ~f acceptable transfer types. The first array element is compared to all list elements, then the second array element, until every array element has been tried. Thus, the array should contain the optimal transfer types first.
If your class provides special operations, you can call XferListSearchO yourself.
The prototype for XferListSearchO is:
STATUS EXPORTED XferListSearch(
) ;
OBJECT listObject,
TAG ids[],
SIZEOF
P TAG pld
idsLen,
The parameters are:
listObject The transfer list object sent to the sender.
ids The list of transfer types that the receiver supports.
idsLen The number of elements in the ids array.
pId A pointer to the location to receive the matched transfer type.
Performing One-Shot Transfers
If the transfer· type is a one-shot type transfer, the receiver sends msgXferGet to the sender. The message takes a pointer to a transfer buffer. Transfer buffers can take on a number of forms. XFER.H defines the following types of transfer buffers:
• XFER_FIXED_BUF transfers up to 256 bytes in a single transfer.
174 PENPOINT ARCHITECTURAL REFERENCE Part 9 I Utility Classes
• XFER_BUF transfers a variable length buffer (of up to 64K bytes).
• XFER_ASCII_METRICS is used to transfer ASCII metrics. This type is only used by xferASCIIMetrics transfer type.
• XFER . .:OBJECT is used to transfer an arbitrary object.
The type of transfer buffer depends on the transfer type. Table 83-4 lists the various one-shot transfer types and the corresponding buffer type. (The information in this table was obtained from XFER.H, which includes the transfer buffer type as a comment when defining the transfer types. If you define your own transfer types, it is a good idea to follow this practice.)
ircm$lrer Type liJfferlype
xferString XFER_FlXED _BUF
xferLongString XFER_BUF
xferName XFER_FlXED _BUF
xfer FullPathN arne XFER_FlXED _BUF
xferFlatLocator XFER_FlXED _BUF
xferASCIIMetrics XFER_ASCII_METRICS
xferRTF (stream protocol)
xferScribbleObject XFER_OBJECT
xferPicSegObject XFER_OBJECT
If you define your own transfer types, you can use these transfer buffers or you can define your own transfer buffers. Of course, transfer types that you create are known only to your senders and receivers.
Fixed-Length BuRer Transfers
If the transfer type is xferString, xferName, xferFu1IPathName, or xferFlatLocator, the argument to msgXferGet is a pointer to an XFER_FlXED_BUF structure, which contains:
id The transfer type.
buf A 256 byte buffer that contains the data.
len The length of the data in buf.
Variable-Length BuRer Transfers
If the transfer type is xferLongString, the argument to msgXferGet is a pointer to an XFER_BUF structure, which contains:
id The transfer type.
pBuf A pohlter to a buffer that contains the data.
len The length of the data in buf.
CHAPTER 83 / TRANSFER CLASS 175 Performing One-Shot Transfers
The buffer indicated by pBuf must be shared. The sender should allocate the buffer by calling OSSharedMemAllocO or by calling OSHeapBlockAllocO with a shared heap such as osProcessSharedHeapld.
When the receiver has read the data from the shared buffer, it should deallocate the buffer (a shared buffer does not have to be allocated and deallocated by the same task).
When the message sends back XFER_BUF, the len field contains the length of the data in pBuf.
Whenever possible, the client that knows how big the data is should allocate the shared buffer.
Whenever possible, the client that requested the data should deallocate the shared buffer.
ASCII Metrics Transfers 83.5~3
If the transfer type is XferASCIIMetrics, the argument to msgXferGet is a pointer to an XFER_ASCII_METRICS structure, which contains:
id The transfer type.
When the sender returns msgXferGet, XFER~SCII_METRICS contains:
first The text index of the first character in the range.
length The length of the text range.
level The parts of text being transferred. The level enables word processors to apply the correct styles to the data moved into a document. The possible values are:
0 Ignore 1 characters 2 words 3 sentences 4 paragraphs
This example shows a receiver sending msgXferGet to a sender.
STATUS GetShortString(
P_TAG pID, II pointer to ID from XferMatch P MY DATA pMyData) II pointer to instance data XFER_FIXED_BUF fbi II Fixed buffer
STATUS status;
fb.id = *pID;
fb.data = pMyData;
status = ObjectSendUpdate(msgXferGet, pMyData->sender, &fb);
if (status >= stsOK)
{
strncpy(pMyData~>pFixedData, fb.buf, fb.len);
pMyData->fixedLen = fb.len;
return stsOK;
176 PENPOINT ARCHITECTURAL REFERENCE Part 9 / Utility Classes
Replying to One-Shot Transfers
When the sender receives msgXferGet, it should move the information into the buffer and return the message. This example shows how the sender responds when it receives msgXferGet:
II
Handle msgXferGet for fixed data STATUS ReplyFixedData(P_XFER_FIXED_BUF pArgs)
P MY DATA *myData;
II
pointer for data STATUS rstatus;II
returned status rstatus = stsOK;II
Find data to transfer FindData(mydata);if (myData->len > 256)
{
pArgs->len = 256;
rstatus = stsTrunc;
II
data truncated elsepArgs->len = myData->len;
strncpy(pArgs->buf, myData->data, pArgs->len);
return rstatus;