Module ubf_client

Description
Data Types
Function Index
Function Details

UBF client-side public API.

Description

UBF client-side public API.

This module implements most of the commonly-used client-side functions required to talk to UBF servers:

connect() to a UBF server
rpc() to make a synchronous call to a connected UBF server
stop() a connection
install_handler() to add a callback function to handle asynchronous notifications from theUBF server to your client process.

Note that this library can support UBF(A), EBF, JSF, TBF, PBF, and ABF transport. See the connect() function arguments for details.

This module also provides an alternative client-side function for calling's UBF contract manager and a UBF contract's implementation without any side-effects: lpc() to make a synchronous local procedure call to a contract's implementation.

See the documentation for the TBD module for extra commentary on writing an UBF server implementation module.

Data Types

address()

address() = string() | ip_address()

A DNS hostname or IP address.

connect_options()

connect_options() = list({proto, ubf | ebf | jsf | tbf | pbf | abf})

An OTP-style property list, see 'proplists' module for details.

ip_address()

ip_address() = string() | tuple()

An IP address in string form, e.g. "127.0.0.1" (IPv4) or "::1" (IPv6), or in tuple form (see documentation for Erlang's 'inet' module for details).

plugin_module_list()

plugin_module_list() = list(atom())

A list of plugin module names that will be passed to ubf_plugin_meta_stateful:new() or ubf_plugin_meta_stateless:new() for client initialization.

tcp_port()

tcp_port() = integer()

A TCP port number.

timeout()

timeout() = integer() | infinity

An Erlang-style timeout value.

Function Index

connect/2	Connect to a UBF server at address Host + TCP port Port.
connect/3	Connect to a UBF server at address Host + TCP port Port.
connect/4	Connect to a UBF server at address Host + TCP port Port, or at pid/registered name Server.
install_default_handler/1	Install a default handler function (callback-style) for asynchronous UBF messages.
install_handler/2	Install a handler function (callback-style) for asynchronous UBF messages.
lpc/2	Perform a synchronous LPC (local procedure) call with the state 'none'.
lpc/3	Perform a synchronous LPC (local procedure) call with the specified state.
lpc/4
rpc/2	Perform a synchronous RPC call.
rpc/3	Perform a synchronous RPC call.
sendEvent/2	Send an asynchronous UBF message.
stop/1	Stop a UBF client process.

Function Details

connect/2

connect(Host::address(), Port::tcp_port()) -> {ok, pid(), service()} | {error, term()}

Connect to a UBF server at address Host + TCP port Port.

connect/3

connect(Host::address(), Port::tcp_port(), Timeout::timeout()) -> {ok, pid(), service()} | {error, term()}

Connect to a UBF server at address Host + TCP port Port.

connect/4

connect(X::address() | plugin_module_list(), Y::tcp_port() | pid() | atom(), Options::proplist(), Timeout::timeout()) -> {ok, pid(), service()} | {error, term()}

Connect to a UBF server at address Host + TCP port Port, or at pid/registered name Server.

When using the alternate form, the first two arguments are:

Plugins: a plugin_module_list().
Server: either a process id (pid()) or process registered name (atom()) for an already-started UBF server.

See the docs for ubf_server:start_link() for a description of the Options proplist.

install_default_handler/1

install_default_handler(Pid::pid()) -> ack

Install a default handler function (callback-style) for asynchronous UBF messages.

The default handler function, drop_fun/1, does nothing.

install_handler/2

install_handler(Pid::pid(), Fun::function()) -> ack

Install a handler function (callback-style) for asynchronous UBF messages.

The handler fun Fun should be a function of arity 1. When an asynchronous UBF message is received, the callback function will be called with the UBF message as its single argument. The Fun is called by the ubf client process so the Fun can crash and/or block this process.

If your handler fun must maintain its own state, then you must use an intermediate anonymous fun to bind the state. See the usage of the irc_client_gs:send_self/2 fun as an example. The send_self() fun is actually arity 2, but the extra argument is how the author, Joe Armstrong, maintains the extra state required to deliver the async UBF message to the process that is executing the event loop processing function, irc_client_gs:loop/6.

NOTE: It is not recommended that a UBF client return the bare atom 'timeout' in response to any RPC call.

Generated EDoc, $Id$