DCC chat/send requests and replies.

Typedefs
typedef void(*	irc_dcc_callback_t )(irc_session_t *session, irc_dcc_t id, int status, void *ctx, const char *data, unsigned int length)
	A common DCC callback, used to inform you about the current DCC state or event.
Functions
int	irc_dcc_chat (irc_session_t *session, void *ctx, const char *nick, irc_dcc_callback_t callback, irc_dcc_t *dccid)
	Initiates a DCC CHAT.
int	irc_dcc_msg (irc_session_t *session, irc_dcc_t dccid, const char *text)
	Sends the message to the specific DCC CHAT.
int	irc_dcc_accept (irc_session_t *session, irc_dcc_t dccid, void *ctx, irc_dcc_callback_t callback)
	Accepts a remote DCC CHAT or DCC RECVFILE request.
int	irc_dcc_decline (irc_session_t *session, irc_dcc_t dccid)
	Declines a remote DCC CHAT or DCC RECVFILE request.
int	irc_dcc_sendfile (irc_session_t *session, void *ctx, const char *nick, const char *filename, irc_dcc_callback_t callback, irc_dcc_t *dccid)
	Sends a file via DCC.
int	irc_dcc_destroy (irc_session_t *session, irc_dcc_t dccid)
	Destroys a DCC session.

---

Typedef Documentation

typedef void(* irc_dcc_callback_t)(irc_session_t *session, irc_dcc_t id, int status, void *ctx, const char *data, unsigned int length)

A common DCC callback, used to inform you about the current DCC state or event.

Parameters:

	session	An IRC session which generates the callback
	id	A DCC session id.
	status	An error status. 0 means no error, otherwise error code.
	ctx	A user-supplied context.
	data	Data supplied (if available)
	length	data length (if available)

This callback is called for all DCC functions when state change occurs.

For DCC CHAT, the callback is called in next circumstances:

• status is LIBIRC_ERR_CLOSED: connection is closed by remote peer. After returning from the callback, the DCC session is automatically destroyed.
• status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error (connect error, accept error, recv error, send error). After returning from the callback, the DCC session is automatically destroyed.
• status is 0: new chat message received, data contains the message (null-terminated string), length contains the message length.

For DCC SEND, while file is sending, callback called in next circumstances:

• status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error (connect error, accept error, recv error, send error). After returning from the callback, the DCC session is automatically destroyed.
• status is 0: new data received, data contains the data received, length contains the amount of data received.

For DCC RECV, while file is sending, callback called in next circumstances:

• status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error (connect error, accept error, recv error, send error). After returning from the callback, the DCC session is automatically destroyed.
• status is 0, and data is 0: file has been received successfully. After returning from the callback, the DCC session is automatically destroyed.
• status is 0, and data is not 0: new data received, data contains the data received, length contains the amount of data received.

---

Function Documentation

int irc_dcc_accept	(	irc_session_t *	session,
		irc_dcc_t	dccid,
		void *	ctx,
		irc_dcc_callback_t	callback
	)

Accepts a remote DCC CHAT or DCC RECVFILE request.

Parameters:

	session	An initiated and connected session.
	dccid	A DCC session ID, returned by appropriate callback.
	ctx	A user-supplied DCC session context, which will be passed to the DCC callback function. May be NULL.
	callback	A DCC callback function, which will be called when anything is said by other party. Must not be NULL.

Returns:

Return code 0 means success. Other value means error, the error code may be obtained through irc_errno().

This function accepts a remote DCC request - either DCC CHAT or DCC FILE. After the request is accepted, the supplied callback will be called, and you can start sending messages or receiving the file.

This function should be called only after either event_dcc_chat_req or event_dcc_send_req events are generated, and should react to them. It is possible not to call irc_dcc_accept or irc_dcc_decline immediately in callback function - you may just return, and call it later. However, to prevent memory leaks, you must call either irc_dcc_decline or irc_dcc_accept for any incoming DCC request.

See also:

irc_dcc_decline event_dcc_chat_req event_dcc_send_req

int irc_dcc_chat	(	irc_session_t *	session,
		void *	ctx,
		const char *	nick,
		irc_dcc_callback_t	callback,
		irc_dcc_t *	dccid
	)

Initiates a DCC CHAT.

Parameters:

	session	An initiated and connected session.
	ctx	A user-supplied DCC session context, which will be passed to the DCC callback function. May be NULL.
	nick	A nick to DCC CHAT with.
	callback	A DCC callback function, which will be called when anything is said by other party. Must not be NULL.
	dccid	On success, DCC session ID will be stored in this var.

Returns:

Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function requests a DCC CHAT between you and other user. For newbies, DCC chat is like private chat, but it goes directly between two users, and bypasses IRC server. DCC CHAT request must be accepted by other side before you can send anything.

When the chat is accepted, terminated, or some data is received, the callback function is called. See the details in irc_dcc_callback_t declaration.

Possible error responces for this command from the RFC1459:

• LIBIRC_RFC_ERR_NORECIPIENT
• LIBIRC_RFC_ERR_NOTEXTTOSEND
• LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
• LIBIRC_RFC_ERR_NOTONCHANNEL
• LIBIRC_RFC_ERR_NOTOPLEVEL
• LIBIRC_RFC_ERR_WILDTOPLEVEL
• LIBIRC_RFC_ERR_TOOMANYTARGETS
• LIBIRC_RFC_ERR_NOSUCHNICK

See also:

irc_dcc_callback_t irc_dcc_msg

int irc_dcc_decline	(	irc_session_t *	session,
		irc_dcc_t	dccid
	)

Declines a remote DCC CHAT or DCC RECVFILE request.

Parameters:

	session	An initiated and connected session.
	dccid	A DCC session ID, returned by appropriate callback.

Returns:

Return code 0 means success. Other value means error, the error code may be obtained through irc_errno().

This function declines a remote DCC request - either DCC CHAT or DCC FILE.

This function should be called only after either event_dcc_chat_req or event_dcc_send_req events are generated, and should react to them. It is possible not to call irc_dcc_accept or irc_dcc_decline immediately in callback function - you may just return, and call it later. However, to prevent memory leaks, you must call either irc_dcc_decline or irc_dcc_accept for any incoming DCC request.

Do not use this function to close the accepted or initiated DCC session. Use irc_dcc_destroy instead.

See also:

irc_dcc_accept irc_callbacks_t::event_dcc_chat_req irc_callbacks_t::event_dcc_send_req irc_dcc_destroy

int irc_dcc_destroy	(	irc_session_t *	session,
		irc_dcc_t	dccid
	)

Destroys a DCC session.

Parameters:

	session	An initiated and connected session.
	dccid	A DCC session ID.

Returns:

Return code 0 means success. Other value means error, the error code may be obtained through irc_errno().

This function closes the DCC connection (if available), and destroys the DCC session, freeing the used resources. It can be called in any moment, even from callbacks or from different threads.

Note that when DCC session is finished (either with success or failure), you should not destroy it - it will be destroyed automatically.

int irc_dcc_msg	(	irc_session_t *	session,
		irc_dcc_t	dccid,
		const char *	text
	)

Sends the message to the specific DCC CHAT.

Parameters:

	session	An IRC session.
	dccid	A DCC session ID, which chat request must have been accepted.
	text	Message text. Must not be NULL.

Returns:

Return code 0 means success. Other value means error, the error code may be obtained through irc_errno().

This function is used to send the DCC CHAT messages. DCC CHAT request must be initiated and accepted first (or just accepted, if initiated by other side).

See also:

irc_dcc_chat

int irc_dcc_sendfile	(	irc_session_t *	session,
		void *	ctx,
		const char *	nick,
		const char *	filename,
		irc_dcc_callback_t	callback,
		irc_dcc_t *	dccid
	)

Sends a file via DCC.

Parameters:

	session	An initiated and connected session.
	ctx	A user-supplied DCC session context, which will be passed to the DCC callback function. May be NULL.
	nick	A nick to send file via DCC to.
	filename	A file name to sent. Must be an existing file.
	callback	A DCC callback function, which will be called when file sent operation is failed, progressed or completed.
	dccid	On success, DCC session ID will be stored in this var.

Returns:

Return code 0 means success. Other value means error, the error code may be obtained through irc_errno(). Any error, generated by the IRC server, is available through irc_callbacks_t::event_numeric.

This function generates a DCC SEND request to send the file. When it is accepted, the file is sent to the remote party, and the DCC session is closed. The send operation progress and result can be checked in callback. See the details in irc_dcc_callback_t declaration.

Possible error responces for this command from the RFC1459:

• LIBIRC_RFC_ERR_NORECIPIENT
• LIBIRC_RFC_ERR_NOTEXTTOSEND
• LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
• LIBIRC_RFC_ERR_NOTONCHANNEL
• LIBIRC_RFC_ERR_NOTOPLEVEL
• LIBIRC_RFC_ERR_WILDTOPLEVEL
• LIBIRC_RFC_ERR_TOOMANYTARGETS
• LIBIRC_RFC_ERR_NOSUCHNICK

See also:

irc_dcc_callback_t