Share via


AssociateFile

AssociateFile

The AssociateFile function associates the supplied file HANDLE with an asynchronous file I/O context. The HANDLE must have been created with the FILE_FLAG_OVERLAPPED flag.

Syntax

        PFIO_CONTEXT 
AssociateFile( HANDLE  hFile ) ;

Parameters

  • hFile
    A file handle (HANDLE) created using CreateFile(Ex) with the FILE_FLAG_OVERLAPPED flag set for asynchronous I/O operations.

Return Values

This function returns a reference to an FIO_CONTEXT structure. This structure has the file handle as one of its members.

Remarks

When the structure is returned, is has an initial reference count of one. Each increment of the reference count must be decremented using the ReleaseContext function. All handles associated with this function should be released using the ReleaseContext function.

When the reference count goes to zero, the referenced FIO_CONTEXT structure and the associated file handle are released (closed).

This function is normally used to associate a previously created file handle with an FIO_CONTEXT so that this handle can be used perform file I/O operations using methods on various MailMsg interfaces. Use of these methods is not required, but simplifies many of the most routine asynchronous file I/O operations.

Requirements

  Windows NT/2000: Requires Windows 2000.   Windows 95/98: Unsupported.   Header: Declared in filehc.h; include filehc.h.   Library: Use fcachdll.lib.

See Also

Concepts

FIOWriteFile
FIOReadFile
FIO_CONTEXT
ReleaseContext