|
|
| Previous | Next |
Starts a file transfer receive operation.
Syntax
NSFile.FtsStartFileTransferReceive( SrcAddr, Port Filter, DestPath, Attrib, Flags )
Parameters
SrcAddr
The IP address of the intended source. You must use a string that consists of four numbers separated by periods. Each of the four numbers must be a number from 0 through 255. A typical address is 239.4.7.54. If a null string (“”) is entered, then the first local address is used. Typically, this is entered if the caller wants to receive by unicast. Also, for unicast transfers, the host name or local address can be entered.
Port
Sets the IP port. You must use a number from 1 through 65535.
Filter
Sets the file path filter, allowing the receiver to specify filter paths. You must use a string that can be resolved into a file path. Paths can include environment variables (such as %TEMP%) or wild cards (such as * and ?). This parameter is typically used to match files to determine which files to receive. For example, if the pattern *.avi is used, only the files with an .avi extension are copied.
DestPath
Sets the path of the intended destination. You must use a string that can be resolved into a file path. Paths can include environment variables (such as %TEMP%) or wild cards (such as * and ?). The receiver can override the desired destination by using this parameter. This parameter is typically used for renaming files or choosing a specific directory. For example, specifying *.avi renames all received file extensions to .avi. Do not supply a value for this parameter if you intend to receive URLs for cache-stuffing.
Attrib
Sets the filter attributes of the files to be copied. If 0 (zero) is specified, then no filtering is performed. The following numbers are valid, and can be combined for multiple attributes. For example, a file can be read-only and hidden, and have the numeric value of 3.
| Value | Description |
| 0 | The file or directory has no other attributes set. This attribute is valid only if used alone. |
| 1 | The file or directory is read-only. Applications can read the file, but cannot write to it or delete it. In the case of a directory, applications cannot delete it. |
| 2 | The file or directory is hidden. It is not included in an ordinary directory listing. |
| 4 | The file or directory is part of, or is used exclusively by, the operating system. |
| 16 | The file or directory is a directory. |
| 32 | The file or directory is an archive file or directory. Applications use this flag to mark files for backup or removal. |
| 256 | The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file must be deleted by the application as soon as it is no longer needed. |
| 2048 | The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories. |
| 4096 | The data of the file is not immediately available. This indicates that the file data has been physically moved to offline storage. |
Flags
Sets the manner in which copied files are created on the destination. If 0 (zero) is specified, the defaults are chosen. The defaults are chosen based on the type of address and port (for example, a multicast address default includes forward error-correction). The following numbers are valid. and can be combined for multiple flags. For example, to continue on error and copy directory structures only, the numeric value is 24. Starting out with a value of 1 is required if you are receiving files from the Windows Media™ Administrator application (you can add flag values to this number), because this application sends files by using forward error-correction. In addition, adding the flag value of 1024 (asynchronous receive) is recommended so that your receive application does not stop while receiving files.
| Decimal value | Description |
| 1 | Use forward error-correction (FEC). This flag is required for multicast transfers that are sent using the Windows Media Administrator application. The transfer expected by the receiver is sent using forward error-correction. Redundant information is sent so that if no more than a specified percentage of the packets is lost, the file still is copied. If this flag is set and a connection-oriented transfer (for example, TCP) is attempted, this method returns E_INVALIDARG. FEC is meant for connectionless transfers. such as UDP. |
| 2 | Create a file even if an error occurs in the transfer process. This must be used only by applications that can process potentially corrupt files. |
| 4 | Copy hidden and system files. |
| 8 | Continue on error. Continue transfer operation even if an error occurs while copying one file in a group of files. |
| 16 | Copy directory structure only; do not copy files. |
| 32 | Remove destination files even if the read-only bit is set. |
| 64 | Copy only if the file exists in the destination directory. |
| 128 | Copy source files depending on whether the source file date is later than the date on the destination file. |
| 256 | Copy all attributes of the source file to the destination file. If this flag is not set, the read-only attribute is reset. |
| 512 | Copy using only short names (8.3 characters). |
| 1024 | Copy asynchronously. This flag is recommended for multicast transfers that are sent using the Windows Media Administrator application. If this flag is not set, the browser “freezes” until the transfer is completed. If an application can spawn threads, it can receive synchronously withoutstopping. This flag (asynchronous) is recommended for scripting languages. |
| 2048 | Copy only if the copy does not replace files. |
| 4096 | Destination path is a file. If the file received is a directory and this flag is set, E_FAIL is returned; the transfer cannot take place, and Result cannot be set. |
| 8192 | Destination path is a directory. If the file received is a file and this flag is set, E_FAIL is returned; the transfer cannot take place, and Result cannot be set. |
| 16384 | Receive files continuously. If set, this flag results in the File Transfer object receiving files continuously until either the transfer is cancelled by the sender or receiver, or there is a fatal error (for example, E_OUTOFMEMORY). The object keeps receiving if the individual receive calls return S_OK or non-fatal errors, such as STG_E_FILENOTFOUND. This flag must be set only if the asynchronous flag is also set. Otherwise, the transfer call fails. And an E_INVALIDARG error message is generated. If this flag is set and all the arguments are valid, the File Transfer object loops until the transfer is explicitly cancelled. If the receiver starts to receive files continuously but then attempts to cancel and start over, the FtsOnTransferCompleted event must be processed to make sure that the cancellation has taken place. Also, if this flag is set, a notification request for a completed transfer must be registered, so that if the transfer is cancelled by the sender, the receiver can continue receiving by starting another receive operation with a new File Transfer object. However, if this flag is set, the receiver never times out. In addition, if this flag is set, the File Transfer object also sets the Continue On Error flag. In continuous mode, once the FTS loops back and starts another listen, all statistical properties (bytes, packets, and so on) are reset. To retrieve statistical properties for each transfer, you must register for an FtsOnTransferCompleted callback and check the statistics in that subroutine. In non-continuous mode, the statistical properties are not reset after the transfer, so you can check the statistics after the transfer is completed, as long as you do not start a new transfer before reading the statistics. |
| 32768 | Do not merge flags. The default behavior is to combine (bitwise OR) the flags of the sender and receiver, and resolve all conflicts in favor of the receiver. If the receiver does not set this flag, this allows the sender to specify flags that can be resolved only by the receiver (for example, copy only newer files). |
| 65536 | Copy source subdirectories to destination subdirectories. This flag is set implicitly if either the copy directory structure only or copy empty directories flags are set. |
| 131072 | If a file with the archive bit set is copied, reset the archive bit after copying. |
| 262144 | Copy empty directories |
Return Values
This method does not return a value. However, it does return a Microsoft COM HRESULT error code to the Error object inVBScript.
The following codes are passed to the Error object.
| Decimal value | Mnemonic | Description |
| 0 | S_OK | The request to start a receive operation was successful. A transfer can start successfully, but can later fail. The Result property must be read when a transfer is completed to make sure that no error occurred after the transfer started. |
| -2147467260 | E_ABORT | Transfer was canceled. The cancellation can come from the sender or the receiver. To determine whether the receiver or the sender cancelled the transfer, the receiver can set a variable whenever it cancels a transfer. |
| -2147467259 | E_FAIL | The request to receive cannot take place for an unspecified reason. |
| -2147287038 | STG_E_FILENOTFOUND | The request to receive cannot take place because a file has not been found or no file has been found that matched a filter. |
| -2147024882 | E_OUTOFMEMORY | The request to receive cannot take place because the File Transfer object is out of memory. |
| -2147024809 | E_INVALIDARG | The request to receive cannot take place because an invalid argument was supplied. |
| -2147023436 | ERROR_TIMEOUT | The request to receive cannot take place because the receiver timed out. (This value is converted to an HRESULT.) |
| -2147023840 | ERROR_SERVICE_ALREADY_RUNNING | The request to receive cannot take place because the File Transfer service is busy with another transfer. (This value is converted to an HRESULT.) |
Remarks
To revoke a specific status callback, you must match the pattern of parameters used to request the callback. For example, suppose a call is made with FtsRegisterStatusCallback(0,10,0,0,0,0,0,0,100,0,0), which requests a notification for every 10 percent of the data bytes of the file transfer as well as for every 100 duplicate packets received. That particular notification can be revoked only by the matching call: FtsRevokeStatusCallback(0,10,0,0,0,0,0,0,100,0). FtsRegisterStatusCallback has 11 parameters, and FtsRevokeStatusCallback has only 10. The revoke does not use the Param parameter.
To receive a multicast transfer, enter a multicast address for the source address. For multicast addresses, the first number in the IP address string must be from 224 through 239 (that is, range from 224.0.0.0 through 239.255.255.255). Addresses starting with 239 are usually reserved for corporate intranets, and are not passed beyond a firewall. Do not use an address from 224.0.0.0 through 224.0.0.255, because those addresses are reserved for multicast session announcements.
To receive a unicast file transfer, enter a null string (“”) for the source address, and enter an appropriate port number. For example, if a null string is entered for the source address and port 2000 is specified, the receiver starts listening on the first local address and on port 2000.
When neither the “Destination Path is a File” nor the “Destination Path is a Directory” flag is set, the File Transfer object uses the following logic to determine whether a file or directory is created at the destination.
| If the intended destination is ... | And the actual destination has... | then the following is created ... |
| A file named “A” | No file of the same name | A file named “A.” |
| A directory named “B” | No directory of the same name | A directory named “B.” |
| A file named “A” | A directory named “A” | A file named “A” inside the directory named “A.” |
| A directory named “B” | A file named “B” | A file named “B.” Every file that would have been in directory “B” is copied to the file named “B.” The last file copied is the contents of the file “B.” |
For the sender, wild cards are used to create collections of files and directories, so any ambiguity at the destination is resolved in favor of directories. For the receiver, wild cards are used for matching, so any ambiguity at the destination is resolved in favor of files. In general, the caller must specify exactly what he or she wants to have created at the destination, especially if he or she cannot be sure which files and directories are at the destination.
| Previous | Next |