FtsRegisterStatusCallback Method

Registers a transfer notification request callback.

Syntax

NSFile.FtsRegisterStatusCallback( Cur, Per, Data, Tot, Pack, Drop, Corr, Bogus, Dup, Flags, Param )

Parameters

Cur

Number of file data bytes that are transferred before each notification occurs. This parameter does not include file header bytes or other non-data file information, such as redundancy bytes. For example, specifying 8192 triggers an FtsOnTransferProgress notification for every 8 KB of file data bytes transferred.

Per

Percent of file data bytes that are transferred before each notification occurs. This parameter does not include file header bytes or other non-data file information, such as redundancy bytes. For example, specifying 10 triggers an FtsOnTransferProgress notification for every 10 percent of the file data bytes that are transferred.

Data

Total data bytes (for all files requested) that are transferred before each notification occurs. This parameter does not include file header bytes or other non-data file information, such as redundancy bytes. For example, specifying 8192 triggers an FtsOnTransferProgress notification for every 8 KB of file data bytes transferred, even if this includes more than one file.

Tot

Total bytes (for all files requested) that are transferred before each notification occurs, including file header bytes or other non-data file information. such as redundancy bytes. For example, specifying 8192 triggers an FtsOnTransferProgress notification for every 8 KB of file bytes transferred, even if this includes more than one file.

Pack

Number of packets that are transferred before each notification occurs. For example, specifying 100 triggers an FtsOnTransferProgress notification for every 100 packets transferred

Drop

Number of packets that are dropped before each notification occurs. For example, specifying 50 triggers an FtsOnTransferProgress notification for every 50 packets dropped.

Corr

Number of packets that are corrected before each notification occurs. For example, specifying 25 triggers 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 triggers 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 happens if a file transfer is taking place and the receiving address starts getting audio packets on the same address.

Dup

Number of duplicate packets that are received before each notification occurs. For example, specifying 5 triggers 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 defaults to a “Transfer completed” notification (the same value as 8).

Param

A parameter used by the caller to identify different calls. The content is arbitrarily chosen by the caller. Any Long value is valid.

Return Values

This method does not return a value. However, it does return a Microsoft COM HRESULT error code to the Error object in VBScript.

The following codes are passed to the Error object.

Remarks

Each parameter is independent, and more than one kind of request can be sent in a single call to this method. Typing 0 (zero) in a parameter indicates that you do not want to be notified about 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.

For asynchronous transfers, it is recommended that a default notification be registered before calling FtsStartFileTransferReceive. The default call for an object named object is:

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 is notified only every 100 bytes. The granularity of each type of notification is specific to the implementation.

The caller always receives 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 receives five notifications. Alternatively, if the caller requests notification every 100 bytes and only 10 bytes are sent, the caller receives 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 objectcloses, all notifications are also destroyed.