PFEvents
==================

It is a class in C++ interface and a structure in C interface.

*C++ (_C_API is not defined)*

.. code-block::

	class PFEvents
	{
	public:
        // The events from NF_EventHandler

		virtual void threadStart() = 0;

		virtual void threadEnd() = 0;

		virtual void tcpConnectRequest(NFAPI_NS ENDPOINT_ID id, NFAPI_NS PNF_TCP_CONN_INFO pConnInfo) = 0;

		virtual void tcpConnected(NFAPI_NS ENDPOINT_ID id, NFAPI_NS PNF_TCP_CONN_INFO pConnInfo) = 0;
		
		virtual void tcpClosed(NFAPI_NS ENDPOINT_ID id, NFAPI_NS PNF_TCP_CONN_INFO pConnInfo) = 0;

		virtual void udpCreated(NFAPI_NS ENDPOINT_ID id, NFAPI_NS PNF_UDP_CONN_INFO pConnInfo) = 0;
		
		virtual void udpConnectRequest(NFAPI_NS ENDPOINT_ID id, NFAPI_NS PNF_UDP_CONN_REQUEST pConnReq) = 0;

		virtual void udpClosed(NFAPI_NS ENDPOINT_ID id, NFAPI_NS PNF_UDP_CONN_INFO pConnInfo) = 0;

        // New object is ready for filtering
		virtual void dataAvailable(NFAPI_NS ENDPOINT_ID id, PFObject * pObject) = 0;
		
        // A part of content is available for examining.
		virtual PF_DATA_PART_CHECK_RESULT dataPartAvailable(NFAPI_NS ENDPOINT_ID id, PFObject * pObject) = 0;

        // The library calls this functions to post the filtered data buffers
        // to destination, and to control the state of filtered connections.

		virtual NF_STATUS tcpPostSend(NFAPI_NS ENDPOINT_ID id, const char * buf, int len) = 0;

		virtual NF_STATUS tcpPostReceive(NFAPI_NS ENDPOINT_ID id, const char * buf, int len) = 0;

		virtual NF_STATUS tcpSetConnectionState(NFAPI_NS ENDPOINT_ID id, int suspended) = 0;

		virtual NF_STATUS udpPostSend(NFAPI_NS ENDPOINT_ID id, const unsigned char * remoteAddress, 
										const char * buf, int len, NFAPI_NS PNF_UDP_OPTIONS options) = 0;

		virtual NF_STATUS udpPostReceive(NFAPI_NS ENDPOINT_ID id, const unsigned char * remoteAddress, 
										const char * buf, int len, NFAPI_NS PNF_UDP_OPTIONS options) = 0;

		virtual NF_STATUS udpSetConnectionState(NFAPI_NS ENDPOINT_ID id, int suspended) = 0;
	};

*C (_C_API is defined)*

.. code-block::

	typedef struct _PFEvents_c
	{
        // The events from NF_EventHandler
		void (PFAPI_CC *threadStart)();

		void (PFAPI_CC *threadEnd)();

		void (PFAPI_CC *tcpConnectRequest)(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo);

		void (PFAPI_CC *tcpConnected)(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo);
		
		void (PFAPI_CC *tcpClosed)(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo);

		void (PFAPI_CC *udpCreated)(ENDPOINT_ID id, PNF_UDP_CONN_INFO pConnInfo);
		
		void (PFAPI_CC *udpConnectRequest)(ENDPOINT_ID id, PNF_UDP_CONN_REQUEST pConnReq);

		void (PFAPI_CC *udpClosed)(ENDPOINT_ID id, PNF_UDP_CONN_INFO pConnInfo);

        // New object is ready for filtering
		void (PFAPI_CC *dataAvailable)(ENDPOINT_ID id, PFObject_c * pObject);
		
        // A part of content is available for examining.
		PF_DATA_PART_CHECK_RESULT (PFAPI_CC *dataPartAvailable)(ENDPOINT_ID id, PFObject_c * pObject);

        // The library calls this functions to post the filtered data buffers
        // to destination, and to control the state of filtered connections.

		NF_STATUS (PFAPI_CC *tcpPostSend)(ENDPOINT_ID id, const char * buf, int len);

		NF_STATUS (PFAPI_CC *tcpPostReceive)(ENDPOINT_ID id, const char * buf, int len);

		NF_STATUS (PFAPI_CC *tcpSetConnectionState)(ENDPOINT_ID id, int suspended);

		NF_STATUS (PFAPI_CC *udpPostSend)(ENDPOINT_ID id, const unsigned char * remoteAddress, 
										const char * buf, int len,
										PNF_UDP_OPTIONS options);

		NF_STATUS (PFAPI_CC *udpPostReceive)(ENDPOINT_ID id, const unsigned char * remoteAddress, 
										const char * buf, int len,
										PNF_UDP_OPTIONS options);

		NF_STATUS (PFAPI_CC *udpSetConnectionState)(ENDPOINT_ID id, int suspended);

	} PFEvents_c, *PPFEvents_c;


.. cpp:function:: void threadStart();

	:description: Called immediately after starting the filtering thread. Use this event for thread-specific initialization, e.g. calling CoInitialize() etc.

.. cpp:function:: void threadEnd();

	:description: Called before stopping the thread.

.. cpp:function:: void tcpConnectRequest(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo);

	:description: Called before establishing an outgoing TCP connection, when NF_INDICATE_CONNECT_REQUESTS flag is enabled in an appropriate rule. It is possible to modify the fields filteringFlag and remoteAddress in pConnInfo structure. The changes are applied to the connection. 

.. cpp:function:: void tcpConnected(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo);

	:description: Called after establishing incoming or outgoing TCP connection.

.. cpp:function:: void tcpClosed(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo);

	:description: Called after closing a TCP connection.

.. cpp:function:: void udpCreated(ENDPOINT_ID id, PNF_UDP_CONN_INFO pConnInfo);

	:description: Called after creating UDP socket.

.. cpp:function:: void udpConnectRequest(ENDPOINT_ID id, PNF_UDP_CONN_REQUEST pConnReq);

	:description: Called before establishing an outgoing UDP connection, when NF_INDICATE_CONNECT_REQUESTS flag is enabled in an appropriate rule. It is possible to modify the fields filteringFlag and remoteAddress in pConnInfo structure. The changes are applied to the connection.

.. cpp:function:: void udpClosed(ENDPOINT_ID id, PNF_UDP_CONN_INFO pConnInfo);

	:description: Called after closing a socket.

.. cpp:function:: void dataAvailable(ENDPOINT_ID id, PFObject * pObject);

	:description: The library calls this function when a new classified object is ready for filtering. After filtering post the object to destination using pf_postObject() function. Do not try to delete pObject. It's contents are destroyed when the function returns. If the object must be filtered in other thread, make a copy of PFObject using clone() method.

.. cpp:function:: PF_DATA_PART_CHECK_RESULT dataPartAvailable(ENDPOINT_ID id, PFObject * pObject);

	:description: This function is called when a part of a large data object is received, when an appropriate filter supports indicating data parts. It is possible to check the available contents, and return a flag, specifying how to filter the rest of object content. The function is not called when full object was received in one packet.

	Possible return values:

		DPCR_MORE_DATA_REQUIRED
			Continue receiving the data and indicate the same object with more content via dataPartAvailable.

		DPCR_FILTER
			Stop calling dataPartAvailable, wait until receiving the full content and indicate it via dataAvailable.

		DPCR_FILTER_READ_ONLY
			Same as DPCR_FILTER, but the content goes to destination immediately, and the object in dataAvailable will have read-only flag.

		DPCR_BYPASS
			Do not call dataPartAvailable or dataAvailable for the current object, just passthrough it to destination.

		DPCR_BLOCK
			Blocks the transmission of the current object.

		DPCR_UPDATE_AND_BYPASS
			Post the updated content in PFObject to session and bypass the rest of data as-is.

		DPCR_UPDATE_AND_FILTER_READ_ONLY
			Post the updated content in PFObject to session and indicate the full object via dataAvailable in read-only mode.


The following functions are called to post the filtered buffers to destination:

.. cpp:function:: NF_STATUS tcpPostSend(ENDPOINT_ID id, const char * buf, int len);

	:description: Assumed a call to nf_tcpPostSend(id, buf, len)

.. cpp:function:: NF_STATUS tcpPostReceive(ENDPOINT_ID id, const char * buf, int len);

	:description: Assumed a call to nf_tcpPostReceive(id, buf, len)

.. cpp:function:: NF_STATUS tcpSetConnectionState(ENDPOINT_ID id, int suspended);

	:description: Assumed a call to nf_tcpSetConnectionState(id, suspended)

.. cpp:function:: NF_STATUS udpPostSend(ENDPOINT_ID id, const unsigned char * remoteAddress, const char * buf, int len);

	:description: Assumed a call to nf_udpPostSend(id, remoteAddress, buf, len)

.. cpp:function:: NF_STATUS udpPostReceive(ENDPOINT_ID id, const unsigned char * remoteAddress, const char * buf, int len);

	:description: Assumed a call to nf_udpPostReceive(id, remoteAddress, buf, len)

.. cpp:function:: NF_STATUS udpSetConnectionState(ENDPOINT_ID id, int suspended);

	:description: Assumed a call to nf_udpSetConnectionState(id, suspended)