gboolean afdal_request VortexConnection connection,
VortexOnFrameReceived  return_function,
AfDalRequestReturnData  request_type,
AfDalFunc  usr_function,
gpointer  usr_data,
gchar *  service_name,
  ...
 

Perform a request to a remote Af-Arch server.

Performs a request to a server select by connection. This function is meant to be used by libafdal* library level.

Because this function is somewhat hard to use, it is supposed you are using an STUB connector, automatically generated by the Af-Gen tool, to avoid using afdal_request function directly.

STUB connectors makes all the work of taking user parameters for the service invocation and apply them to afdal_request function.

Let's see an example about how to use afdal_request function and to introduce the STUB connector concept:

 gboolean afdal_af_gmovil_brand_new (gchar * brand, 
                                     AfDalSimpleFunc usr_function,
                                     gpointer usr_data) 
 {
    VortexConnection *connection = NULL;
    gboolean result;
    connection = afdal_session_get_connection ("af-gmovil", NULL);
    if (!connection)
       return FALSE;
    coyote_xml_check_str (brand);
    result =
         afdal_request (connection, afdal_request_process_simple_data,
                        (AfDalFunc) usr_function, usr_data,
                        "af_gmovil::brand::new", 
                        "", COYOTE_XML_ARG_STRING, brand, 
                        NULL);
    coyote_xml_check_str_to_free (brand);
    return result;
 }

As you can see, the STUB connector provides a simple api to the programmer, which means less time programming. That is, the STUB connector is just a piece of code to simply the service invocation through afdal_request function. In this case, the STUB connector provides the following interface:

 gboolean afdal_af_gmovil_brand_new (gchar * brand, 
                                     AfDalSimpleFunc usr_function,
                                     gpointer usr_data);

This way to invoke the service called "af_gmovil::brand::new" located at "af-gmovil" server (no matter where is this server running, that's a question handled by AfDal layer), we have a simple api based on 3 parameters.

Of course, if you are planning to do a more complex job while making service invocation you are likely to need use afdal_request function directly.

As a consecuence:

  • It is really unusual to use afdal_request function directly, inside the user space code. Usual situation is that the STUB connector uses afdal_request function. This component, the STUB connector, is automatically generated by the Af-Gen tool.

  • If you pretend to extend Af-Arch service invocation to add features or modify its actual behaviour you will need to programm something similiar to the STUB connector, adding or extending actual behaviour, but finally using afdal_request function directly.

Parameters:
connection An already created conection to a remote server.
return_function Function to be executed by coyote layer when an xml message arrives from the other peer.
request_type Request type being performed.
usr_function User space function to be executed by libafdal when an xml message has been processed.
usr_data User space data to be passed to usr_function.
service_name The service's name we are going to send to.
Returns:
Returns TRUE if request could be sent ok or FALSE if fails. This doesn't means actually the request was successfully executed. It just means the invocation have finished successfully.