Registers a transfer notification request callback. Each parameter is independent and more than one kind of request can be sent in a single call to this method. Putting 0 (zero) in a parameter indicates that you do not want to be notified for that particular kind of request. Each unique collection of parameter values makes up a separate notification request. If the caller wants to revoke the request, each unique collection of parameter values must be used in the call to FtsRevokeStatusCallback.
When a requested notification occurs, the corresponding event is triggered. By placing code that reads the appropriate properties in the corresponding subroutine, you can process the transfer notification.
object.FtsRegisterStatusCallback Cur Per Data Tot Pack Drop Corr Bogus Dup Flags Param
Parameter Description Cur Number of file data bytes that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would trigger an FtsOnTransferProgress notification for every 8KB of file data bytes transferred. Per Percent of file data bytes that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 10 would trigger an FtsOnTransferProgress notification for every 10 percent of the file data bytes transferred. Data Total data bytes (for all files requested) that will transfer before each notification occurs. Does not include file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would trigger an FtsOnTransferProgress notification for every 8KB of file data bytes transferred, even if this included more than one file. Tot Total bytes (for all files requested) that will transfer before each notification occurs, including file header bytes or other non-data file information such as redundancy bytes. For example, specifying 8192 would trigger an FtsOnTransferProgress notification for every 8KB of file bytes transferred, even if this included more than one file. Pack Number of packets that will transfer before each notification occurs. For example, specifying 100 would trigger an FtsOnTransferProgress notification for every 100 packets transferred Drop Number of packets that are dropped before each notification occurs. For example, specifying 50 would trigger an FtsOnTransferProgress notification for every 50 packets dropped. Corr Number of packets that are corrected before each notification occurs. For example, specifying 25 would trigger an FtsOnTransferProgress notification for every 25 packets received and corrected. Bogus Number of bogus packets that are received before each notification occurs. For example, specifying 25 would trigger an FtsOnTransferProgress notification for every 25 bogus packets received. A bogus packet is a packet that is received on the same IP address and port as the receiver is listening for, but which is not part of an expected file transfer operation. For example, this would happen if a file transfer were taking place and the receiving address started getting audio packets on the same address. Dup Number of duplicate packets that are received before each notification occurs. For example, specifying 5 would trigger an FtsOnTransferProgress notification for every five duplicate packets received. Flags The following flags are used by this method to define the type of notification requested. Multiple flags can be used on each request. If 0 (zero) is specified, the file transfer object would default to a "transfer completed" notification (the same value as 8).
Value Description 0 Notification requested for a completed transfer operation (same as 8). 4 Notification requested for the start of a transfer operation. 8 Notification requested for a completed transfer operation (same as 0). 16 Notification requested for the start of each individual file transfer operation. 32 Notification requested for a completed transfer operation for each individual file. 64 Notification requested for any change in the status of the file transfer. Param A parameter used by the caller to identify different calls. The content is arbitrarily chosen by the caller. Any Long numer is valid.
This method does not return a value. However, this object does return a Microsoft COM HRESULT error code to the Visual Basic Script Error object.
The following codes are passed to the Error object:
Decimal Value Description (HRESULT) 0 The action requested was successful. (S_OK) 1 The action requested is already taking place. (S_FALSE) -2147467259 The action requested could not take place for an unspecified reason.(E_FAIL) -2147024882 The action requested could not take place because the file transfer object was out of memory. (E_OUTOFMEMORY) -2147024809 The action requested could not take place because an invalid argument was supplied. (E_INVALIDARG)
For asynchronous transfers, it is recommended that a default notification be registered before calling FtsStartFileTransferReceive. The default call for an object named object would be:
call object.FtsRegisterStatusCallback(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)File transfer notifications have an internal granularity. For example, if 100 bytes at a time are transferred, and the caller requests notification every 10 bytes, the caller will be notified only every 100 bytes. The granularity of each type of notification is implementation-specific.
The caller will always receive a notification even if the increment of change is larger than that requested. For example, if the caller requests notification every 10 bytes, and a 45-byte file is sent, the caller will receive five notifications. Or if the caller requests notification every 100 bytes and only 10 bytes are sent, the caller will receive one notification.
This method registers callbacks for the progress and changes of status of a file transfer operation. Progress notifications are processed by FtsOnTransferProgress. Status notifications are processed by FtsOnStatusChanged, as well as the status-specific events such as FtsOnTransferStarted, FtsOnTransferCompleted, FtsOnFileTransferStarted, and FtsOnFileTransferCompleted.
Notification callbacks do not have to be revoked. When the file transfer object shuts down, all notifications are destroyed also.
Return to File Transfer Reference.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.