Starts a file transfer receive operation.
Syntax
NSFile.FtsStartFileTransferReceive( SrcAddr, Port Filter, DestPath, Attrib Flags )
Parameters
SrcAddr
The Internet Protocol (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 would be 239.4.7.54. If a null string ("") is entered, then the first local address is used. Typically this would be entered if the caller wanted 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. Note that 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 were used, only the files with an .avi extension would be copied.
DestPath
Sets the path of the intended destination. You must use a string that can be resolved into a file path. Note that 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 would rename 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 may be combined for multiple attributes. For example, a file can be read-only and hidden and would 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 should 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. 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. Note that the defaults are chosen based on the type of address and port (for example, a multicast address default would include forward error-correction). The following numbers are valid and may be combined for multiple flags. For example, if you wanted to continue on error and copy directory structures only, the numeric value would be 24. Starting out with a value of 1 is required if you are receiving files from the Microsoft® NetShow™ Administrator application (you can add flag values to this number), since 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 will not "freeze" while receiving.
| Decimal Value | Description |
| 1 | Use forward error-correction ( FEC). This flag is required for multicast transfers that are sent using the NetShow Administrator application. The transfer expected by the receiver was 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 will still be copied. If this flag is set and a connection-oriented transfer (for example, TCP) is attempted, this method will return E_INVALIDARG. FEC is meant for connectionless transfers such as UDP. |
| 2 | Create a file even if an error occurs in the transfer process. Note that this should 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 in the copying of one file in a group of files. |
| 16 | Copy directory structure only; do not copy files. |
| 32 | Overwrite 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 will be reset. |
| 512 | Copy using short names (8.3 characters) only. |
| 1024 | Copy asynchronously. This flag is recommended for multicast transfers that are sent using the NetShow Administrator application. If this flag is not set, the browser will "freeze" until the transfer is completed. If an application can spawn threads, it can receive synchronously without "freezing." This flag (asynchronous) is recommended for scripting languages. |
| 2048 | Copy only if the copy does not overwrite files. |
| 4096 | Destination path is a file. If the file received is a directory and this flag is set, E_FAIL will be returned; the transfer will not take place, and Result will not be set. |
| 8192 | Destination path is a directory. If the file received is a file and this flag is set, E_FAIL will be returned; the transfer will not take place, and Result will not be set. |
| 16384 | Receive files continuously. If set, this flag will result in the File Transfer Service 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 would keep receiving if the individual receive calls return S_OK or non-fatal errors like STG_E_FILENOTFOUND. This flag should be set only if the asynchronous flag is also set. Otherwise the transfer call will fail and an E_INVALIDARG error message will be generated. If this flag is set and all the arguments are valid, the File Transfer object will loop until the transfer is explicitly cancelled. If the receiver starts to receive files continuously but then wants to cancel and start over, the FtsOnTransferCompleted event should be processed to make sure that the cancel has taken place. Also, if this flag is set, a notification request for a completed transfer should 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 will never time out. In addition, if this flag is set, the File Transfer object will also set the continue on error flag. Note that 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 should 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 completes, as long as you don't 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 than 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 Microsoft Visual Basic® Script Error object.
The following codes are passed to the Error object:
| Decimal Value | Description (HRESULT) |
| 0 | The request to start a receive operation was successful. (S_OK) Note that a transfer can start successfully, but may later fail. The Result property should be read when a transfer is completed to make sure that no error occurred after the transfer started. |
| -2147467260 | Transfer was canceled. The cancel could have come from the sender or the receiver. (E_ABORT) To determine whether the receiver or the sender cancelled the transfer, the receiver could set a variable whenever it cancels a transfer. |
| -2147467259 | The request to receive could not take place for an unspecified reason.(E_FAIL) |
| -2147287038 | The request to receive could not take place because a file was not found or no file was found that matched a filter. (STG_E_FILENOTFOUND) |
| -2147024882 | The request to receive could not take place because the File Transfer object was out of memory. (E_OUTOFMEMORY) |
| -2147024809 | The request to receive could not take place because an invalid argument was supplied. (E_INVALIDARG) |
| -2147023436 | The request to receive could not take place because the receiver timed out. (ERROR_TIMEOUT converted to an HRESULT) |
| -2147023840 | The request to receive could not take place because the file transfer service is busy with another transfer. (ERROR_SERVICE_ALREADY_RUNNING converted to an HRESULT) |
Remarks
To receive a multicast transfer, enter a multicast address for the source address. For multicast addresses, the first number in the IP address string should 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, as 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 will start 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 will use the following logic to determine whether a file or directory will be created on the destination.
| If the intended destination is ... | and the actual destination has... | then the following will be 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" will be created 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" will be copied to the filename "B." The last file copied will be the contents of the file "B." |
Note that for the sender, wild cards are used to create collections of files and directories, so any ambiguity on the destination will be resolved in favor of directories. For the receiver, wild cards are used for matching, so any ambiguity on the destination will be resolved in favor of files. In general, the caller should specify exactly what he or she wants created on the destination, especially if he or she cannot be sure what files and directories will be on the destination.
© 1996-1998 Microsoft Corporation. All rights reserved.