WriteFile Subroutine

Purpose

Writes data to a socket.

Syntax

#include <iocp.h>
boolean_t WriteFile (FileDescriptor, Buffer, WriteCount, AmountWritten, Overlapped)
HANDLE FileDescriptor;
LPVOID Buffer;
DWORD WriteCount;
LPDWORD AmountWritten;
LPOVERLAPPED Overlapped;

Description

The WriteFile subroutine writes the number of bytes specified by the WriteCount parameter from the buffer indicated by the Buffer parameter to the FileDescriptor parameter. The number of bytes written is saved in the AmountWritten parameter. The Overlapped parameter indicates whether or not the operation can be handled asynchronously.

The WriteFile subroutine returns a boolean (an integer) indicating whether or not the request has been completed.

The WriteFile subroutine is part of the I/O Completion Port (IOCP) kernel extension.

Note: This subroutine only works to a socket file descriptor. It does not work with files or other file descriptors.

Parameters

Item	Description
FileDescriptor	Specifies a valid file descriptor obtained from a call to the socket or accept subroutines.
Buffer	Specifies the buffer from which the data will be written.
WriteCount	Specifies the maximum number of bytes to write.
AmountWritten	Specifies the number of bytes written. The parameter is set by the subroutine.
Overlapped	Specifies an overlapped structure indicating whether or not the request can be handled asynchronously.

Return Values

Upon successful completion, the WriteFile subroutine returns a boolean indicating the request has been completed.

If the WriteFile subroutine is unsuccessful, the subroutine handler performs the following functions:

Returns a value of 0 to the calling program.
Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable, see the link in the Related Information section of this document.

Error Codes

Item	Description
EINPROGRESS	The write request can not be immediately satisfied and will be handled asynchronously. A completion packet will be sent to the associated completion port upon completion.
EAGAIN	The write request cannot be immediately satisfied and cannot be handled asynchronously.
EINVAL	The FileDescriptor is invalid.

Examples

The following program fragment illustrates the use of the WriteFile subroutine to synchronously write data to a socket:

void buffer;
int amount_written;
b=WriteFile (34, &buffer, 128, &amount_written, NULL);

The following program fragment illustrates the use of the WriteFile subroutine to asynchronously write data to a socket:

void buffer;
int amount_written;
LPOVERLAPPED overlapped;
b = ReadFile (34, &buffer, 128, &amount_written, overlapped);

Note: The request will only be handled asynchronously if it cannot be immediately satisfied.