Player::RequestFile

Defined in: C4Messages.h

Attempts to initiate a file transfer from a player.

Prototype

void RequestFile(const char *name);

Parameters

name A pointer to the name of the file to be transferred.

Description

A call to RequestFile causes a message to be sent to a player to request the file whose name is given by the name parameter. The RequestFile function returns immediately and the Message Manager listens for a response to the request.

If the request is accepted, the file transfer is initiated and the player will call its completion procedure when the transfer is complete. If the request is denied for some reason (for instance, the file does not exist), then an error message is registered and the player's completion procedure is invoked.

The Completable base class of the Player class is used to signal the completion of a file transfer or that an error arose during a file transfer. The completion procedure has the prototype

void FileTransferComplete(Player *player, void *data);

where player is the player from whom the file was requested, and data is the user-defined pointer passed to the Completable::SetCompletionProc function. The implementation of this completion procedure should first call Player::GetFileTransferResult to determine whether the file was successfully transferred or whether an error occurred. This function returns one of the following file transfer result codes.

`kTransferOkay`	The file transfer succeeded.
`kTransferPending`	A file transfer is already in progress. Each player allows only one file transfer to be pending at a time.
`kTransferFileNotFound`	The file does not exist on the sending machine.
`kTransferFileUnreadable`	The file could not be read on the sending machine.
`kTransferFileUnwriteable`	The file could not be written on the receiving machine.
`kTransferConnectionLost`	The connection was closed or timed out during the file transfer.