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.