| |
| INT RegisterEvent( |
| |
UINT nEventId, |
|
| |
FTPEVENTPROC lpEventProc, |
|
| |
DWORD_PTR dwParam |
|
| ); |
The RegisterEvent method registers an event handler for
the specified event.
Parameters
- nEventId
- An unsigned integer which specifies which event should be
registered with the specified callback function. One of the
following values may be used:
| Value |
Description |
| FTP_EVENT_CONNECT |
The control connection to the server has completed. |
| FTP_EVENT_DISCONNECT |
The server has closed the control connection to the
client. The client should read any remaining data and
disconnect. |
| FTP_EVENT_OPENFILE |
The data connection to the server has completed. |
| FTP_EVENT_CLOSEFILE |
The server has closed the data connection to the client.
The client should read any remaining data and close the data
channel. |
| FTP_EVENT_READFILE |
Data is available to read by the calling process. No
additional messages will be posted until the client has read at
least some of the data. This event is only generated if the
client is in asynchronous mode. |
| FTP_EVENT_WRITEFILE |
The client can now write data. This notification is sent
after a connection has been established, or after a previous
attempt to write data has failed because it would result in a
blocking operation. This event is only generated if the client is
in asynchronous mode. |
| FTP_EVENT_TIMEOUT |
The network operation has exceeded the specified timeout
period. The client application may attempt to retry the
operation, or may disconnect from the server and report an error
to the user. |
| FTP_EVENT_CANCEL |
The current operation has been canceled. Under most
circumstances the client should disconnect from the server and
re-connect if needed. After an operation has been canceled, the
server may abort the connection or refuse to accept further
commands from the client. |
| FTP_EVENT_COMMAND |
A command has been issued by the client and the server
response has been received and processed. This event can be used
to log the result codes and messages returned by the server in
response to actions taken by the client. |
| FTP_EVENT_PROGRESS |
The client is in the process of sending or receiving a file
on the data channel. This event is called periodically during a
transfer so that the client can update any user interface
components such as a status control or progress bar. |
| FTP_EVENT_GETFILE |
This event occurs when a file download has completed.
If multiple files are being downloaded, this event will be
generated for each file. |
| FTP_EVENT_PUTFILE |
This event occurs when a file upload has completed. If
multiple files are being uploaded, this event will be generated
for each file. |
| FTP_EVENT_QUEUE |
This event occurs during a queued file transfer. It
only occurs when a file is being transferred using the
CFtpQueue class and the internal state of the queue has changed.
The handle passed to this event will be a handle to the queue,
not a client connection to the server. |
- lpEventProc
- Specifies the procedure-instance address of the application
defined callback function. For more information about the callback
function, see the description of the FtpEventProc callback
function. If this parameter is NULL, the callback for the specified
event is disabled.
- dwParam
- A user-defined integer value that is passed to the callback
function. If the application targets the x86 (32-bit) platform, this
parameter must be a 32-bit unsigned integer. If the application
targets the x64 (64-bit) platform, this parameter must be a 64-bit
unsigned integer.
Return Value
If the method succeeds, the return value is zero. If the method
fails, the return value is FTP_ERROR. To get extended error
information, call GetLastError.
Remarks
The RegisterEvent method associates a
callback function with a specific event. The event handler is an
FtpEventProc function that is invoked when the event
occurs. Arguments are passed to the function to identify the client
session, the event type and the user-defined value specified when the
event handler is registered. If the event occurs because of an error
condition, the error code will be provided to the handler.
This method is typically used to register an event handler
that is invoked while a file is being uploaded or downloaded. The
FTP_EVENT_PROGRESS event will only be generated
periodically during the transfer to ensure the application is not
flooded with event notifications. It is guaranteed that at least one
FTP_EVENT_PROGRESS notification will occur at the beginning of the
transfer, and one at the end of the transfer when it has completed.
The callback function specified by the lpEventProc
parameter must be declared using the __stdcall
calling convention. This ensures the arguments passed to the event
handler are pushed on to the stack in the correct order. Failure to
use the correct calling convention will corrupt the stack and cause
the application to terminate abnormally.
The dwParam parameter is commonly used to identify the
class instance which is associated with the event that has occurred.
Applications will cast the this pointer to a
DWORD_PTR value when calling this function, and then the event handler
will cast it back to a pointer to the class instance. This gives the
handler access to the class member variables and methods.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: csftpv11.lib
See Also
DisableEvents,
EnableEvents,
FreezeEvents,
GetTransferStatus,
FtpEventProc
|
|