paweld/lazarus-ccr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
c66386067c
lazarus-ccr/components/beepfp/vortex/vortex_handlers.inc

1316 lines
50 KiB
PHP
Raw Blame History

(*
* LibVortex: C Header file to Free Pascal translation.
* Copyright (C) 2009, Wimpie Nortje <wimpienortje@gmail.com>
*)
(*
* LibVortex: A BEEP (RFC3080/RFC3081) implementation.
* Copyright (C) 2008 Advanced Software Production Line, S.L.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* as published by the Free Software Foundation; either version 2.1
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this program; if not, write to the Free
* Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
* 02111-1307 USA
*
* You may find a copy of the license under this software is released
* at COPYING file. This is LGPL software: you are welcome to develop
* proprietary applications using this library without any royalty or
* fee but returning back any change, improvement or addition in the
* form of source code, project image, documentation patches, etc.
*
* For commercial support on build BEEP enabled solutions contact us:
*
* Postal address:
* Advanced Software Production Line, S.L.
* C/ Antonio Suarez Nº 10,
* Edificio Alius A, Despacho 102
* Alcalá de Henares 28802 (Madrid)
* Spain
*
* Email address:
* info@aspl.es - http://www.aspl.es/vortex
*)
{*
* \defgroup vortex_handlers Vortex Handlers: Handlers used across Vortex Library for async notifications.
}
{*
* \addtogroup vortex_handlers
* @
}
{*
* @brief Async notification for listener creation.
*
* Functions using this handler:
* - \ref vortex_listener_new
*
* Optional handler defined to report which host and port have
* actually allocated a listener peer. If host and port is null means
* listener have failed to run.
*
* You should not free any parameter received, vortex system will do
* this for you. If you want to actually keep a copy you should use
* axl_strdup.
*
* @param host the final host binded
* @param port the final port binded
* @param status the listener creation status.
* @param message the message reporting the listener status creation.
* @param user_data user data passed in to this async notifier.
}
type
TVortexListenerReady = procedure (host:Pchar; port:longint; status:TVortexStatus; amessage:Pchar; user_data:TaxlPointer);cdecl;
{*
* @brief Async notification for listener creation, similar to \ref
* VortexListenerReady but providing the reference for the \ref
* VortexConnection created (representing the listener created).
*
* Functions using this handler:
* - \ref vortex_listener_new_full
*
* Optional handler defined to report which host and port have
* actually allocated a listener peer. If host and port is null means
* listener have failed to run.
*
* You should not free any parameter received, vortex system will do
* this for you. If you want to actually keep a copy you should use
* axl_strdup (deallocating your copy with axl_free).
*
* This function is similar to \ref VortexListenerReady but it also
* notifies the connection created.
*
* @param host The final host binded.
*
* @param port The final port binded.
*
* @param status The listener creation status.
*
* @param message The message reporting the listener status creation.
*
* @param connection The connection representing the listener created
* (or a NULL reference if status is not \ref VortexOk).
*
* @param user_data user data passed in to this async notifier.
}
type
TVortexListenerReadyFull = procedure (host:Pchar; port:longint;
status:TVortexStatus; amessage:Pchar; connection:PVortexConnection;
user_data:TaxlPointer);cdecl;
{*
* @brief Async notification for connection creation process.
*
* Functions using this handler:
* - \ref vortex_connection_new
*
* Optional handler defined to report the final status for a \ref
* vortex_connection_new process. This handler allows you to create a
* new connection to a vortex server (BEEP enabled peer) in a
* non-blocking (or asynchronously way).
*
* Once the connection creation process have finished, no matter which
* is the final result, the handler is invoked.
*
* @param connection The connection created (or not, check \ref vortex_connection_is_ok).
* @param user_data user defined data passed in to this async notifier.
}
type
TVortexConnectionNew = procedure (connection:PVortexConnection;
user_data:TaxlPointer);cdecl;
{*
* @brief Async notification for start channel message received for a given profile.
*
* Functions using this handler:
* - \ref vortex_profiles_register
*
* Handler is used to notify peer role that a channel is being asked
* to be created. The handler receives a reference to the connection
* where the channel is being requested.
*
* If peer agree to create the channel axl_true must be
* returned. Otherwise, axl_false must be used.
*
* You can get the reference to the \ref VortexChannel object in
* trasint to be created, by using \ref vortex_connection_get_channel,
* but keep in mind the channel is it transit to be created. This is
* useful if you want to configure something on the channel.
*
* @param channel_num the channel num for the new channel attempted to be created.
* @param connection the connection where the channel is going to be created.
* @param user_data user defined data passed in to this async notifier.
*
* @return axl_true if the new channel can be created or axl_false if not.
}
type
TVortexOnStartChannel = function (channel_num:longint; connection:PVortexConnection;
user_data:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Channel start message received handler with support for
* extended attributes.
*
* In most situations, while using Vortex Library, you can assume the
* default implementation to handle the start channel request.
*
* However, a start message request could have several attributes and
* additional parameters that are notified in the form of a "piggyback",
* to set up new channels, performing especial operations, as happens
* with TLS negotiation.
*
* This handler allows to get start message notification with all
* possible data received.
*
* Here is an channel start message example:
* \code
* <start number='1' serverName='my.domain.com'>
* <profile uri='http://some-unique-profile-uri/mech' encoding='none'>
* <![CDATA[some necessary initial round trip data]]>
* </profile>
* </start>
* \endcode
*
* This handler will notify the channel number being requested, the
* serverName value, the profile requested, the piggyback encoding and
* the optional piggyback.
*
* Keep in mind that the encoding is an implicit attribute. Having it
* not defined yields to the default value 'none', which is
* represented by \ref EncodingNone.
*
* Functions using this handler:
*
* - \ref vortex_profiles_register_extended_start
*
* @param profile The profile being request to create a new channel.
*
* @param channel_num Channel being requested for creation.
*
* @param connection Connection where the channel creation request was
* received.
*
* @param serverName Value for this optional start message
* attribute. This is used
*
* @param profile_content Optional profile content received inside the
* channel start message.
*
* @param profile_content_reply Optional profile content reply to be
* used for channel start reply, it will be freed by the library after
* the reply is sent.
*
* @param encoding Encoding used for the profile content.
*
* @param user_data User defined data to be passed in to the handler
* when it is executed.
*
* @return axl_true if the new channel can be created or axl_false if not.
}
type
TVortexOnStartChannelExtended = function (profile:Pchar; channel_num:longint;
connection:PVortexConnection; serverName:Pchar; profile_content:Pchar;
profile_content_reply:PPchar; encoding:TVortexEncoding; user_data:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Async notification for incoming close channel request.
*
* Functions using this handler:
*
* - \ref vortex_profiles_register
* - \ref vortex_channel_new
*
* This handler allows to control what to do on close channel
* notification. Close notification is received when remote peer wants
* to close some channel.
*
* The handler must return axl_true if the channel can be close, otherwise
* axl_false must be returned.
*
* If you need to not perform an answer at this function, allowing to
* deffer the decision, you can use \ref
* VortexOnNotifyCloseChannel. That handler will allow to hold the
* close channel notification, to later complete the request by
* calling to a finish function.
*
* @param channel_num The channel num requesting to be closed.
*
* @param connection The connection where the channel resides.
*
* @param user_data User defined data passed in to this Async notifier.
*
* @return axl_true if channel can be closed. To reject the close request
* return axl_false.
}
type
TVortexOnCloseChannel = function (channel_num:longint; connection:PVortexConnection;
user_data:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Async notification for incoming close channel requests. This
* handler allows to only receive the notification and defer the
* decision to close or not the channel.
*
* This is an alternative API to \ref VortexOnCloseChannel, that
* allows to configure a handler (this one) to be executed to get
* notification about channel close request (\ref
* vortex_channel_set_close_notify_handler), and later the request is
* completed by calling to \ref vortex_channel_notify_close.
*
* @param channel The channel that was notified to be closed.
*
* @param user_data User defined data to be passed to the handler
* execution.
}
type
TVortexOnNotifyCloseChannel = procedure (channel:PVortexChannel; msg_no:longint;
user_data:TaxlPointer);cdecl;
{*
* @brief Async notifier for frame received event.
*
* Functions using this handler:
* - \ref vortex_profiles_register
* - \ref vortex_channel_new
* - \ref vortex_channel_new_full
* - \ref vortex_channel_new_fullv
* - \ref vortex_channel_set_received_handler
* - \ref vortex_channel_pool_new
* - \ref vortex_channel_queue_reply
*
* This handler allows you to control received frames from remote
* peers. <b>channel</b> parameter is the channel where the
* <b>frame</b> was received. <b>connection</b> parameter represent
* the connection where the channel is running. Finally,
* <b>user_data</b>, is a user defined pointer passed in to this
* function and defined when the handler was registered.
*
* You must not free received frame. Vortex library will do it for you.
* Remember that, if you want to have permanent access to frame payload,
* make a copy. After running this handler, Vortex library will free
* all VortexFrame resources.
*
* @param channel the channel where the frame have been received.
* @param connection the connection where the channel is running
* @param frame the frame received
* @param user_data user defined data passed in to this async notifier.
}
type
TVortexOnFrameReceived = procedure (channel:PVortexChannel; connection:PVortexConnection;
frame:PVortexFrame; user_data:TaxlPointer);cdecl;
{*
* @brief Async notifier for channel creation process.
*
* Function using this handler:
* - \ref vortex_channel_new
*
* This handler allows you to define a notify function that will be
* called once the channel is created or something have failed with
* errors such as timeout reached or channel creation process
* failures.
*
* If something fails, a -1 will be received on channel_num and
* channel will be NULL. Otherwise, you will received the channel
* number created and a reference to channel created. It is not
* needed to hold a reference to channel. You can get it by using
* \ref vortex_connection_get_channel.
*
* In the case an error is found (channel reference is NULL or
* channel_num is -1) you can use \ref
* vortex_connection_pop_channel_error to get more details.
*
* @param channel_num the channel number for the new channel created
* @param channel the channel created
* @param user_data user defined data passed in to this async notifier.
}
type
TVortexOnChannelCreated = procedure (channel_num:longint; channel:PVortexChannel;
conn:PVortexConnection; user_data:TaxlPointer);cdecl;
{*
* @brief Async notifier for Vortex Channel Pool creation.
*
* Function using this handler:
* - \ref vortex_channel_pool_new
*
* This handler allows to make an async notification once the channel
* pool process have finished. Because the channel pool creation
* process can take a long time this handler is really useful to keep
* on doing other things such as interface updating.
*
* @param pool the channel pool created
* @param user_data user defined data passed in to this async notifier.
}
type
TVortexOnChannelPoolCreated = procedure (pool:PVortexChannelPool; user_data:TaxlPointer);cdecl;
{*
* @brief Synchronous handler definition used by the channel pool
* module to create a new channel.
*
* This function allows to notify the user code that a new channel
* must be created for the channel pool. This allows to place the
* channel creation code outside the channel pool module while the
* channel pool features remain the same.
*
* The function has pretty much the same parameters as \ref
* vortex_channel_new, which is quite straightforward, but two
* additional parametes are provided: <b>create_channel_user_data</b>
* and <b>get_next_data</b>. Both a pointers that are defined at the
* vortex_channel_pool_new_full in the first case, and at the \ref vortex_channel_pool_get_next_ready_full.
*
* See \ref vortex_channel_pool_new_full for more information.
*
* @param connection The connection where the channel pool is asking
* to createa a new channel.
*
* @param channel_num The channel number to create.
*
* @param profile The profile for the channel.
*
* @param on_close The on close handler to be executed once received a
* close notification.
*
* @param on_close_user_data The on close handler user data (data
* provided to the on close handler).
*
* @param on_received The frame received handler to be executed one
* data is received. Once the channel is created and returned by \ref
* vortex_channel_pool_get_next_ready or \ref
* vortex_channel_pool_get_next_ready_full this value can be
* reconfigured using \ref vortex_channel_set_received_handler.
*
* @param on_received_user_data User defined data to be passed to the handler.
*
* @param create_channel_user_data User defined data provided at the channel pool creation function.
*
* @return A newly created \ref VortexChannel reference or NULL if it
* fails.
}
type
TVortexChannelPoolCreate = function (connection:PVortexConnection;
channel_num: longint; profile: PChar; on_close: TVortexOnCloseChannel;
on_close_user_data: TaxlPointer; on_received: TVortexOnFrameReceived;
on_received_user_data:TaxlPointer; create_channel_user_data: TaxlPointer
): PVortexChannel;cdecl;
{*
* @brief Async notifier for the channel close process, with support
* for a user defined data.
*
* Function using this handler:
* - \ref vortex_channel_close_full
*
* This function handler works as defined by \ref
* VortexOnClosedNotification but without requiring an optional user
* data pointer. See also \ref vortex_channel_close.
*
* This handler allows you to defined a notify function that will be
* called once the channel close indication is received. This is
* mainly used by \ref vortex_channel_close to avoid caller get
* blocked by calling that function.
*
* Data received is the channel num this notification applies to, the
* channel closing status and if was_closed is axl_false (the channel was
* not closed) code hold error code returned and msg the message
* returned by remote peer.
*
* @param connection the connection on which the channel was closed
* @param channel_num the channel num identifying the channel closed
* @param was_closed status for the channel close process.
* @param code the code representing the channel close process.
* @param msg the message representing the channel close process.
* @param user_data A user defined pointer established at function
* which received this handler.
}
type
TVortexOnClosedNotificationFull = procedure (connection:PVortexConnection;
channel_num:longint; was_closed:Taxl_bool; code:Pchar; msg:Pchar;
user_data:TaxlPointer);cdecl;
{*
* @brief Async notifier for the channel close process
*
* Function using this handler:
* - \ref vortex_channel_close
*
* In the case you require to provide a user defined pointer to the
* close function you can try \ref vortex_channel_close_full (and its
* handler \ref VortexOnClosedNotificationFull).
*
* This handler allows you to defined a notify function that will be
* called once the channel close indication is received. This is
* mainly used by \ref vortex_channel_close to avoid caller get
* blocked by calling that function.
*
* Data received is the channel num this notification applies to, the
* channel closing status and if was_closed is axl_false (the channel was
* not closed) code hold error code returned and msg the message
* returned by remote peer.
*
* @param connection the connection on which the channel was closed
* @param channel_num the channel num identifying the channel closed
* @param was_closed status for the channel close process.
* @param code the code representing the channel close process.
* @param msg the message representing the channel close process.
* @param user_data A user defined pointer established at function
* which received this handler.
}
type
TVortexOnClosedNotification = procedure (channel_num:longint;
was_closed:Taxl_bool; code:Pchar; msg:Pchar);cdecl;
{*
* @brief Defines the writers handlers used to actually send data
* through the underlaying socket descriptor.
*
* This handler is used by:
* - \ref vortex_connection_set_send_handler
*
* @param connection Vortex Connection where the data will be sent.
* @param buffer The buffer holding data to be sent
* @param buffer_len The buffer len.
*
* @return How many data was actually sent.
}
type
TVortexSendHandler = function (connection:PVortexConnection;
buffer:Pchar; buffer_len:longint):longint;cdecl;
{*
* @brief Defines the readers handlers used to actually received data
* from the underlying socket descriptor.
*
* This handler is used by:
* - \ref vortex_connection_set_receive_handler
*
* @param connection The Vortex connection where the data will be received.
* @param buffer The buffer reference used as container for data received.
* @param buffer_len The buffer len use to know the limits of the buffer.
*
* @return How many data was actually received.
}
type
TVortexReceiveHandler = function (connection:PVortexConnection;
buffer:Pchar; buffer_len:longint):longint;cdecl;
{*
* @brief Allows to set a handler that will be called when a
* connection is about being closed.
*
* This method could be used to establish some especial actions to be
* taken before the connection is completely unrefered. This function
* could be used to detect connection broken.
*
* This handler is used by:
* - \ref vortex_connection_set_on_close
*
* <i><b>NOTE:</b> You must not free the connection received at the
* handler. This is actually done by the library. </i>
*
* @param connection The connection that is about to be unrefered.
*
}
type
TVortexConnectionOnClose = procedure (connection:PVortexConnection);cdecl;
{*
* @brief Extended version for \ref VortexConnectionOnClose, which
* also supports passing an user defined data.
*
* This handler definition is the same as \ref
* VortexConnectionOnClose, being notified at the same time, but
* providing an user defined pointer.
*
* See also:
*
* - \ref vortex_connection_set_on_close_full
* - \ref vortex_connection_set_on_close
*
* @param The connection that is about to be closed.
* @param The user defined pointer configured at \ref vortex_connection_set_on_close_full.
*
* @return
}
type
TVortexConnectionOnCloseFull = procedure (connection:PVortexConnection; data:TaxlPointer);cdecl;
{*
* @brief Async handler definition to get a notification for
* connections created at the server side (peer that is able to accept
* incoming connections).
*
* This handler is executed once the connection is accepted and
* registered in the vortex engine. If the function return axl_false, the
* connection will be dropped, without reporting any error to the
* remote peer.
*
* This function could be used as a initial configuration for every
* connection. So, if it is only required to make a connection
* initialization, the handler provided must always return axl_true to
* avoid dropping the connection.
*
* This handler is also used by the TUNNEL profile implementation to
* notify the application layer if the incoming TUNNEL profile should
* be accepted.
*
* This handler is used by:
*
* - \ref vortex_listener_set_on_connection_accepted
*
* @param connection The connection that has been accepted to be
* managed by the listener.
*
* @param data The connection data to be passed in to the handler.
*
* @return axl_true if the connection is finally accepted. axl_false to drop
* the connection, rejecting the incoming connection.
}
//typedef axl_bool (*VortexOnAcceptedConnection) (VortexConnection * connection, axlPointer data);
type
//TVortexOnAcceptedConnection = function (connection:PVortexConnection; data:TaxlPointer):Taxl_bool;cdecl;
TVortexOnAcceptedConnection = function (connection:PVortexConnection; data:TaxlPointer):ptrint;cdecl;
{*
* @brief Async notifications for TLS activation.
*
* Once the process for TLS negotiation have started, using \ref
* vortex_tls_start_negotiation function, the status for such process is notified
* using this handler type definition.
*
* The <i>status</i> value have to be checked in order to know if the
* transport negotiation have finished successfully. Along the previous
* variable, the <i>status_message</i> have a textual diagnostic about
* the current status received.
*
* While invoking \ref vortex_tls_start_negotiation you could provide an user
* space pointer, using the <i>user_data</i> parameter. That user data
* is received on this handler.
*
* Functions using this handler:
* \ref vortex_tls_start_negotiation
*
*
* @param connection The connection where the TLS activation status is
* being notified.
*
* @param status The process status.
*
* @param status_message A textual message representing the process
* status.
*
* @param user_data A user defined pointer established at function
* which received this handler.
}
type
TVortexTlsActivation = procedure (connection:PVortexConnection; status:TVortexStatus;
status_message:Pchar; user_data:TaxlPointer);cdecl;
{*
* @brief Handler definition for those function used to configure if a
* given TLS request should be accepted or denied.
*
* Once a TLS request is received this handler will be executed to
* notify user space application on top of Vortex Library if the request should be denied or not. The
* handler will receive the connection where the request was received
* and an optional value serverName which represents a request to act as
* the server name the value represent.
*
* This handler definition is used by:
* - \ref vortex_tls_accept_negotiation
*
* @param connection The connection where the TLS request was received.
* @param serverName Optional serverName value requesting, if defined, to act as the server defined by this value.
*
* @return axl_true if the TLS request should be accepted. axl_false to deny
* the session TLS-fication.
}
type
TVortexTlsAcceptQuery = function (connection:PVortexConnection; serverName:Pchar):Taxl_bool;cdecl;
{*
* @brief Handler definition for those function allowing to locate the
* certificate file to be used while enabling TLS support.
*
* Once an TLS negotiation is started two files are required to
* enable TLS ciphering: the certificate and the private key. Two
* handlers are used by the Vortex Library to allow user app level to
* configure file locations for both files.
*
* This handler is used to configure location for the certificate
* file. The function will receive the connection where the TLS is
* being request to be activated and the serverName value which hold a
* optional host name value requesting to act as the server configured
* by this value.
*
* The function must return a path to the certificate using a
* dynamically allocated value. Once finished, the Vortex Library will
* unref it.
*
* <b>The function should return a basename file avoiding full path file
* names</b>. This is because the Vortex Library will use \ref
* vortex_support_find_data_file function to locate the file
* provided. That function is configured to lookup on the configured
* search path provided by \ref vortex_support_add_search_path or \ref
* vortex_support_add_search_path_ref.
*
* As a consequence:
*
* - If all certificate files are located at
* <b>/etc/repository/certificates</b> and the <b>serverName.cert</b> is to
* be used <b>DO NOT</b> return on this function <b>/etc/repository/certificates/serverName.cert</b>
*
* - Instead, configure <b>/etc/repository/certificates</b> at \ref
* vortex_support_add_search_path and return <b>servername.cert</b>.
*
* - Doing previous practices will allow your code to be as
* platform/directory-structure independent as possible. The same
* function works on every installation, the only question to be
* configured are the search paths to lookup.
*
*
* @param connection The connection where the TLS negotiation was received.
*
* @param serverName An optional value requesting to as the server
* <b>serverName</b>. This value is supposed to be used to select the
* right certificate file.
*
* This handler is used by:
* - \ref vortex_tls_accept_negotiation
*
* @return A newly allocated value containing the path to the certificate file.
}
type
TVortexTlsCertificateFileLocator = function (connection:PVortexConnection; serverName:PChar):Pchar;cdecl;
{*
* @brief Handler definition for those function allowing to locate the
* private key file to be used while enabling TLS support.
*
* See \ref VortexTlsCertificateFileLocator handler. This handler
* allows to define how is located the private key file used for the
* session TLS-fication.
*
* This handler is used by:
* - \ref vortex_tls_accept_negotiation
*
* @return A newly allocated value containing the path to the private key file.
}
type
TVortexTlsPrivateKeyFileLocator = function (connection:PVortexConnection; serverName:PChar):Pchar;cdecl;
{*
* @brief Handler definition used by the TLS profile, to allow the
* application level to provide the function that must be executed to
* create an (SSL_CTX *) object, used to perform the TLS activation.
*
* This handler is used by:
* - \ref vortex_tls_set_ctx_creation
* - \ref vortex_tls_set_default_ctx_creation
*
* By default the Vortex TLS implementation will use its own code to
* create the SSL_CTX object if not provided the handler. However,
* such code is too general, so it is recomended to provide your own
* context creation.
*
* Inside this function you must configure all your stuff to tweak the
* OpenSSL behaviour. Here is an example:
*
* \code
* axlPointer * __ctx_creation (VortexConnection * conection,
* axlPointer user_data)
*
* SSL_CTX * ctx;
*
* // create the context using the TLS method (for client side)
* ctx = SSL_CTX_new (TLSv1_method ());
*
* // configure the root CA and its directory to perform verifications
* if (SSL_CTX_load_verify_locations (ctx, "your-ca-file.pem", "you-ca-directory"))
* // failed to configure SSL_CTX context
* SSL_CTX_free (ctx);
* return NULL;
*
* if (SSL_CTX_set_default_verify_paths () != 1)
* // failed to configure SSL_CTX context
* SSL_CTX_free (ctx);
* return NULL;
*
*
* // configure the client certificate (public key)
* if (SSL_CTX_use_certificate_chain_file (ctx, "your-client-certificate.pem"))
* // failed to configure SSL_CTX context
* SSL_CTX_free (ctx);
* return NULL;
*
*
* // configure the client private key
* if (SSL_CTX_use_PrivateKey_file (ctx, "your-client-private-key.rpm", SSL_FILETYPE_PEM))
* // failed to configure SSL_CTX context
* SSL_CTX_free (ctx);
* return NULL;
*
*
* // set the verification level for the client side
* SSL_CTX_set_verify (ctx, SSL_VERIFY_PEER, NULL);
* SSL_CTX_set_verify_depth(ctx, 4);
*
* // our ctx is configured
* return ctx;
*
* \endcode
*
* For the server side, the previous example mostly works, but you
* must reconfigure the call to SSL_CTX_set_verify, providing
* something like this:
*
* \code
* SSL_CTX_set_verify (ctx, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, NULL);
* \endcode
*
* See OpenSSL documenation for SSL_CTX_set_verify and SSL_CTX_set_verify_depth.
*
* @param connection The connection that has been requested to be
* activated the TLS profile, for which a new SSL_CTX must be created.
*
* @param user_data An optional user pointer defined at either \ref
* vortex_tls_set_default_ctx_creation and \ref
* vortex_tls_set_ctx_creation.
*
* @return You must return a newly allocated SSL_CTX or NULL if the
* handler must signal that the TLS activation must not be performed.
}
type
TVortexTlsCtxCreation = function (connection:PVortexConnection; user_data:TaxlPointer):TaxlPointer;cdecl;
{*
* @brief Allows to configure a post-condition function to be executed
* to perform an addiontional checking.
*
* This handler is used by:
*
* - \ref vortex_tls_set_post_check
* - \ref vortex_tls_set_default_post_check
*
* The function must return axl_true to signal that checkings are passed,
* otherwise axl_false must be returned. In such case, the connection will
* be dropped.
*
* @param connection The connection that was TLS-fixated and
* addiontional checks was configured.
*
* @param user_data User defined data passed to the function, defined
* at \ref vortex_tls_set_post_check and \ref
* vortex_tls_set_default_post_check.
*
* @param ssl The SSL object created for the process.
*
* @param ctx The SSL_CTX object created for the process.
*
* @return axl_true to accept the connection, otherwise, axl_false must be
* returned.
}
type
TVortexTlsPostCheck = function (connection:PVortexConnection; user_data:TaxlPointer;
ssl:TaxlPointer; ctx:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Pre read handler definition.
*
* This handler definition is mainly used to perform especial
* operations prior to fully accept a connection into the vortex
* library. This handler is detected and invoked in an abstract manner
* from inside the Vortex Reader.
*
* Functions using this handler are:
* - \ref vortex_connection_set_preread_handler
*
* @param connection The connection which is receiving the on pre read
* event.X
}
type
TVortexConnectionOnPreRead = procedure (connection:PVortexConnection);cdecl;
{*
* @brief IO handler definition to allow defining the method to be
* invoked while createing a new fd set.
*
* @param ctx The context where the IO set will be created.
*
* @param wait_to Allows to configure the file set to be prepared to
* be used for the set of operations provided.
*
* @return A newly created fd set pointer, opaque to Vortex, to a
* structure representing the fd set, that will be used to perform IO
* waiting operation at the \ref vortex_io "Vortex IO module".
*
}
type
TVortexIoCreateFdGroup = function (ctx:PVortexCtx; wait_to:TVortexIoWaitingFor):TaxlPointer;cdecl;
{*
* @brief IO handler definition to allow defining the method to be
* invoked while destroying a fd set.
*
* The reference that the handler will receive is the one created by
* the \ref VortexIoCreateFdGroup handler.
*
* @param VortexIoDestroyFdGroup The fd_set, opaque to vortex, pointer
* to a structure representing the fd set to be destroy.
*
}
type
TVortexIoDestroyFdGroup = procedure (fd_set:TaxlPointer);cdecl;
{*
* @brief IO handler definition to allow defining the method to be
* invoked while clearing a fd set.
*
* @param VortexIoClearFdGroup The fd_set, opaque to vortex, pointer
* to a structure representing the fd set to be clear.
*
}
type
TVortexIoClearFdGroup = procedure (fd_set:TaxlPointer);cdecl;
{*
* @brief IO handler definition to allow defining the method to be
* used while performing a IO blocking wait, by default implemented by
* the IO "select" call.
*
* @param VortexIoWaitOnFdGroup The handler to set.
*
* @param The maximum value for the socket descriptor being watched.
*
* @param The requested operation to perform.
*
* @return An error code according to the description found on this
* function: \ref vortex_io_waiting_set_wait_on_fd_group.
}
type
TVortexIoWaitOnFdGroup = function (fd_group:TaxlPointer; max_fds:longint;
wait_to:TVortexIoWaitingFor):longint;cdecl;
{*
* @brief IO handler definition to perform the "add to" the fd set
* operation.
*
* @param fds The socket descriptor to be added.
*
* @param fd_group The socket descriptor group to be used as
* destination for the socket.
*
* @return returns axl_true if the socket descriptor was added, otherwise,
* axl_false is returned.
}
type
TVortexIoAddToFdGroup = function (fds:longint; connection:PVortexConnection;
fd_group:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief IO handler definition to perform the "is set" the fd set
* operation.
*
* @param fds The socket descriptor to be added.
*
* @param fd_group The socket descriptor group to be used as
* destination for the socket.
*
* @param user_data User defined pointer provided to the function.
*
* @return axl_true if the socket descriptor is active in the given fd
* group.
*
}
type
TVortexIoIsSetFdGroup = function (fds:longint; fd_group:TaxlPointer; user_data:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Handler definition to allow implementing the have dispatch
* function at the vortex io module.
*
* An I/O wait implementation must return axl_true to notify vortex engine
* it support automatic dispatch (which is a far better mechanism,
* supporting better large set of descriptors), or axl_false, to notify
* that the \ref vortex_io_waiting_set_is_set_fd_group mechanism must
* be used.
*
* In the case the automatic dispatch is implemented, it is also
* required to implement the \ref VortexIoDispatch handler.
*
* @param fd_group A reference to the object created by the I/O waiting mechanism.
* p
* @return Returns axl_true if the I/O waiting mechanism support automatic
* dispatch, otherwise axl_false is returned.
}
type
TVortexIoHaveDispatch = function (fd_group:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief User space handler to implement automatic dispatch for I/O
* waiting mechanism implemented at vortex io module.
*
* This handler definition is used by:
* - \ref vortex_io_waiting_invoke_dispatch
*
* Do not confuse this handler definition with \ref VortexIoDispatch,
* which is the handler definition for the actual implemenation for
* the I/O mechanism to implement automatic dispatch.
*
* @param fds The socket that is being notified and identified to be dispatched.
*
* @param wait_to The purpose of the created I/O waiting mechanism.
*
* @param connection Connection where the dispatch operation takes
* place.
*
* @param user_data Reference to the user data provided to the dispatch function.
}
type
TVortexIoDispatchFunc = procedure (fds:longint; wait_to:TVortexIoWaitingFor;
connection:PVortexConnection; user_data:TaxlPointer);cdecl;
{*
* @brief Handler definition for the automatic dispatch implementation
* for the particular I/O mechanism selected.
*
* This handler is used by:
* - \ref vortex_io_waiting_set_dispatch
* - \ref vortex_io_waiting_invoke_dispatch (internally)
*
* If this handler is implemented, the \ref VortexIoHaveDispatch must
* also be implemented, making it to always return axl_true. If this two
* handler are implemented, its is not required to implement the "is
* set?" functionality provided by \ref VortexIoIsSetFdGroup (\ref
* vortex_io_waiting_set_is_set_fd_group).
*
* @param fd_group A reference to the object created by the I/O
* waiting mechanism.
*
* @param dispatch_func The dispatch user space function to be called.
*
* @param changed The number of descriptors that changed, so, once
* inspected that number, it is not required to continue.
*
* @param user_data User defined data provided to the dispatch
* function once called.
}
type
TVortexIoDispatch = procedure (fd_group:TaxlPointer; dispatch_func:TVortexIoDispatchFunc;
changed:longint; user_data:TaxlPointer);cdecl;
{*
* @brief Profile mask handler to perform profile filtering functions.
*
* This handler definition is used by:
* - \ref vortex_connection_set_profile_mask
*
* The handler (a mask) is executed for each profile to be
* filtered. The function based on the data received must return axl_true
* (to filter a profile) or axl_false (to not filter it).
*
* The function receives the connection where the filtering is taking
* place, the profile uri and a user defined pointer configured at the
* function used to install the mask, along with some data which is
* optional according to the place that the mask is executed.
*
* Because the profile mask is used by the vortex engine to filter
* profiles at the greeting process and filter profiles at the channel
* creation process, data available on such stages differs.
*
* At the greetings process, only <b>uri</b> is available. The value
* provided for the <b>channel_num</b> is -1 and NULL for
* <b>profile_content</b> and <b>serverName</b>.
*
* At the channel creation process all values are defined (with the
* exception of <b>profile_content</b> and <b>serverName</b> which are
* optional).
*
* @param connection The connection that where the filter process will
* take place.
*
* @param channel_num The channel number that is requested in the
* channel creation stage.
*
* @param uri A uri reference to the profile check if it should be
* filtered.
*
* @param profile_content The piggyback provided at the start channel
* request along with the profile.
*
* @param serverName A request for the connection to act as
* serverName.
*
* @param error_msg Optional variable to configure an error message to
* be returned to the remote peer extending the 554 error used by
* default. The handler can define a textual message on this variable
* (dinamically allocated) and then used by vortex to build the error
* reply. The message configured will be deallocated using
* axl_free. For example, you can use the following:
* \code
* // check we are not at the greetings process and also check error_msg
* // which may not be defined
* if (channel_num > 0 && error_msg)
* (* error_msg) = axl_strdup ("Profile not accepted due to policy configuration");
* // return axl_true to filter the uri
* return axl_true;
*
* \endcode
*
* NOTE: You must not define error_msg and return axl_false.
*
* @param user_data User defined pointer passed to the function.
*
* @return axl_true to filter the uri, axl_false if not.
}
type
TVortexProfileMaskFunc = function (connection:PVortexConnection; channel_num:longint;
uri:Pchar; profile_content:Pchar; serverName:Pchar; error_msg:PPchar;
user_data:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Handler definition for the set of functions that allow the
* users space to control how frames are splited by the vortex
* sequencer process.
*
* This handler is used by the following functions:
*
* - \ref vortex_channel_get_next_frame_size
* - \ref vortex_channel_set_next_frame_size_handler
* - \ref vortex_connection_get_next_frame_size
* - \ref vortex_connection_set_next_frame_size_handler
* - \ref vortex_connection_set_default_next_frame_size_handler
*
* @param channel The channel that is required to return next frame size.
*
* @param next_seq_no This value represent the next sequence number
* for the first octect to be sent on the frame.
*
* @param message_size This value represent the size of the payload to
* be sent.
*
* @param max_seq_no Is the maximum allowed seqno accepted by the
* remote peer. Beyond this value, the remote peer will close the
* connection.
*
* @param user_data User defined pointer passed to the handler when it
* is executed.
*
* @return The amount of payload to use into the next frame to be
* built. The function will return -1 if the channel reference
* received is NULL.
}
type
TVortexChannelFrameSize = function (channel:PVortexChannel; next_seq_no:longint;
message_size:longint; max_seq_no:longint; user_data:TaxlPointer):longint;cdecl;
{*
* @brief Handler used by \ref vortex_connection_get_channel_by_func
* which is called to check if the channel provided must be returned
* as selected.
*
* @param channel The function receives the channel that is asked to
* be selected or not.
*
* @param user_data User defined data which is provided to the \ref
* vortex_connection_get_channel_by_func.
*
* @return axl_true to select the channel, otherwise axl_false must be
* returned.
}
type
TVortexChannelSelector = function (channel:PVortexChannel; user_data:TaxlPointer):Taxl_bool;cdecl;
{*
* @brief Handler definition used to notify that a channel was added
* or removed from a particular connection.
*
* In the case the channel is added, the function is called just after
* it was fully added to the connection. In the case the channel was
* removed, the handler is called just before.
*
* The handler is used the following two functions:
*
* - \ref vortex_connection_set_channel_added_handler
* - \ref vortex_connection_set_channel_removed_handler
*
* This function is handler definition is useful to get notifications
* at the server side for channels created or removed in the case a
* particular operation must be triggered on that moment.
*
* @param channel The channel that is being removed or added to the
* connection.
*
* @param user_data The user defined data that was configured with the
* handle.r
*
}
type
TVortexConnectionOnChannelUpdate = procedure (channel:PVortexChannel; user_data:TaxlPointer);cdecl;
{*
* @brief Handler definition for the set of functions that are called
* during the connection creation and configured by \ref
* vortex_connection_set_connection_actions.
*
* @param ctx The context where the operation is taking place.
*
* @param conn The connection that is notified.
*
* @param new_conn In the case the action creates a new connection
* that must replace the connection received, this variable is used to
* notify the new reference.
*
* @param state The stage during the notification is taking place.
*
* @param user_data User defined data associated to the action. This
* was configured at \ref vortex_connection_set_connection_actions.
*
* @return The function must return a set of codes that are used by
* the library to handle errors. The action must return:
*
* - (-1) in the case an error was found during the action
* processing. In this case, the connection is closed and a closed
* connection is returned to the caller of \ref vortex_connection_new.
*
* - (0) in the case the function want to stop action processing. This
* is useful to block other actions.
*
* - (1) in the case the function executed the action without errors.
*
* - (2) in the case the function creates a new connection and it must
* be replaced, the caller must return (2) and fill the variable
* new_connection. In this case, the action is entirely responsible of
* the connection received and its deallocation.
}
//typedef int (*VortexConnectionAction) (VortexCtx * ctx,
// VortexConnection * conn,
// VortexConnection ** new_conn,
// VortexConnectionStage state,
// axlPointer user_data);
type
TVortexConnectionAction = function (ctx:PVortexCtx; conn:PVortexConnection;
new_conn:PPVortexConnection; state:TVortexConnectionStage; user_data:TaxlPointer):longint;cdecl;
{*
* @brief Handler definition that allows to get a notification that
* the channel is being disconnected from the connection (because the
* connection is closed and in process of being deallocated).
*
* This function is used by:
*
* - \ref vortex_channel_set_closed_handler
*
* NOTE: The connection reference holding the channel should not be
* used from inside this handler.
*
* @param channel The channel about to be unrefered (the reference owned by the connection).
*
* @param user_data User defined pointer configured at: \ref vortex_channel_set_closed_handler.
*
* @see vortex_channel_set_closed_handler
}
type
TVortexOnClosedChannel = procedure (channel:PVortexChannel; user_data:TaxlPointer);cdecl;
{*
* @brief Handler definition that allows a client to print log
* messages itself.
*
* This function is used by:
*
* - \ref vortex_log_set_handler
* - \ref vortex_log_get_handler
*
* @param file The file that produced the log.
*
* @param line The line where the log was produced.
*
* @param log_level The level of the log
*
* @param message The message being reported.
*
* @param args Arguments for the message.
}
type
TVortexLogHandler = procedure (afile:Pchar; line:longint; log_level:TVortexDebugLevel;
amessage:Pchar; args:array of const);cdecl;
{*
* @brief Handler definition used by \ref vortex_async_queue_foreach
* to implement a foreach operation over all items inside the provided
* queue, blocking its access during its process.
*
* @param queue The queue that will receive the foreach operation.
*
* @param item_stored The item stored on the provided queue.
*
* @param position Item position inside the queue. 0 position is the
* next item to pop.
*
* @param user_data User defined optional data provided to the foreach
* function.
}
{$WARNINGS OFF}
type
TVortexAsyncQueueForeach = procedure (queue:PVortexAsyncQueue; item_stored:TaxlPointer;
position:longint; user_data:TaxlPointer);cdecl;
{$WARNINGS ON}
{**
* @brief Handler used by Vortex library to create a new thread. A custom handler
* can be specified using \ref vortex_thread_set_create
*
* @param thread_def A reference to the thread identifier created by
* the function. This parameter is not optional.
*
* @param func The function to execute.
*
* @param user_data User defined data to be passed to the function to
* be executed by the newly created thread.
*
* @return The function returns axl_true if the thread was created
* properly and the variable thread_def is defined with the particular
* thread reference created.
*
* @see vortex_thread_create
*}
{$WARNINGS OFF}
type
TVortexThreadCreateFunc = function(thread_def: PVortexThread; func: TVortexThreadFunc;
user_data: TaxlPointer; args: array of const):Taxl_bool; cdecl;
{$WARNINGS ON}
{**
* @brief Handler used by Vortex Library to release a thread's resources.
* A custom handler can be specified using \ref vortex_thread_set_destroy
*
* @param thread_def A reference to the thread that must be destroyed.
*
* @param free_data Boolean that set whether the thread pointer should
* be released or not.
*
* @return axl_true if the destroy operation was ok, otherwise axl_false is
* returned.
*
* @see vortex_thread_destroy
*}
{$WARNINGS OFF}
type
TVortexThreadDestroyFunc = function (thread_def: PVortexThread; free_data :Taxl_bool): Taxl_bool; cdecl;
{$WARNINGS ON}
{ @ }
Reference in New Issue View Git Blame Copy Permalink