---

client.h File Reference

Convenient high-level interface functions. More...

#include "gale/core.h"
#include "gale/misc.h"
#include "oop.h"

Go to the source code of this file.

Compounds
struct	gale_message
Message Formatting
typedef void*	gale_call_location (struct gale_text name, struct gale_location *loc,void *user)
	Function type to report a complete location lookup. More...
typedef void*	gale_call_packet (struct gale_packet *msg,void *user)
	Function type to report a packed message. More...
typedef void*	gale_call_message (struct gale_message *msg,void *user)
	Function type to report an unpacked message. More...
void	gale_find_location ( oop_source *,struct gale_text, gale_call_location *,void *user)
	Look up a Gale location address. More...
void	gale_find_exact_location ( oop_source *,struct gale_text, gale_call_location *,void *user)
	Look up a Gale location address without alias expansion. More...
void	gale_find_default_location ( oop_source *,gale_call_location *,void *user)
	Look up the default user location. More...
struct gale_text	gale_location_name (struct gale_location *loc)
	Find a location's name. More...
struct gale_key*	gale_location_key (struct gale_location *loc)
	Find the key of a location. More...
const struct gale_map*	gale_location_members (struct gale_location *loc)
	Get the membership list of a location. More...
int	gale_location_receive_ok (struct gale_location *loc)
	Determine if we can receive messages sent to a location. More...
int	gale_location_send_ok (struct gale_location *loc)
	Determine if we can send messages to a location. More...
void	gale_pack_message (oop_source *oop, struct gale_message *msg, gale_call_packet *call,void *user)
	Pack a Gale message into a raw "packet". More...
void	gale_unpack_message (oop_source *oop, struct gale_packet *pack, gale_call_message *func,void *user)
	Unpack a Gale message from a raw "packet". More...
struct gale_text	gale_pack_subscriptions ( struct gale_location **list, int *positive)
	Pack a list of locations into a subscription expression. More...
Connection Management
typedef void*	gale_call_disconnect (struct gale_server *serv,void *user)
	Function type for user-defined notification handler for disconnection. More...
typedef void*	gale_call_connect (struct gale_server *serv, struct gale_text host,struct sockaddr_in addr,void *)
	Function type for user-defined notification handler for connection. More...
struct gale_server*	gale_make_server ( oop_source *oop,struct gale_link *link, struct gale_text server,int avoid_port)
	Connect to a Gale server. More...
void	gale_close (struct gale_server *serv)
	Disconnect from a Gale server. More...
void	gale_on_connect (struct gale_server *serv,gale_call_connect *func,void *user)
	Set a handler to be called when a connection is established. More...
void	gale_on_disconnect (struct gale_server *,gale_call_disconnect *func,void *user)
	Set a handler to be called when a connection is broken. More...
Error Processing
struct gale_error_queue*	gale_make_queue (oop_source *)
	Create an error queue object. More...
void	gale_on_queue (struct gale_error_queue *,gale_call_message *,void *)
	Set a handler to be called when an error message object is generated. More...
gale_call_error	gale_queue_error
	Add an error report to an error queue object. More...
Functions
void	gale_add_id (struct gale_group *group,struct gale_text terminal)
	Add standard identifying fragments to a message. More...

---

Detailed Description

Convenient high-level interface functions.

---

Typedef Documentation

typedef void* gale_call_connect(struct gale_server *serv, struct gale_text host,struct sockaddr_in addr,void *)

Function type for user-defined notification handler for connection. Parameters: serv   The server handle. host   The hostname of the chosen server. addr   The IP address of the chosen server. user   The user-defined parameter to pass the function. Returns: Liboop continuation code (usually OOP_CONTINUE). See also: gale_on_connect()

typedef void* gale_call_disconnect(struct gale_server *serv,void *user)

Function type for user-defined notification handler for disconnection. Parameters: serv   The server handle. user   User-defined parameter. Returns: Liboop continuation code (usually OOP_CONTINUE). See also: gale_on_disconnect()

typedef void* gale_call_location(struct gale_text name, struct gale_location *loc,void *user)

Function type to report a complete location lookup. Parameters: name   Name of the location. loc   Location handle if successful, NULL if unsuccessful. user   User-defined parameter. Returns: Liboop continuation code (usually OOP_CONTINUE). See also: gale_find_location()

typedef void* gale_call_message(struct gale_message *msg,void *user)

Function type to report an unpacked message. Parameters: msg   The message, NULL if unsuccessful. user   User-defined parameter. Returns: Liboop continuation code (usually OOP_CONTINUE). See also: gale_unpack_message()

typedef void* gale_call_packet(struct gale_packet *msg,void *user)

Function type to report a packed message. Parameters: pack   Fully packed message, or NULL if unsuccessful. user   User-defined parameter. Returns: Liboop continuation code (usually OOP_CONTINUE). See also: gale_pack_message()

---

Function Documentation

void gale_add_id ( struct gale_group * group, struct gale_text terminal )

Add standard identifying fragments to a message. Parameters: group   Group to add fragments to. terminal   Terminal (or other "session") identifier for this client.

void gale_close ( struct gale_server * s )

Disconnect from a Gale server. Gracefully closes a Gale server connection. Parameters: serv   The server handle returned by gale_make_server(). See also: gale_make_server()

void gale_find_default_location ( oop_source * oop, gale_call_location * func, void * user )

Look up the default user location. Start looking up the local user's default "personal" location. When the lookup is complete (whether it succeeded or failed), the supplied callback is invoked. Parameters: oop   Liboop event source to use. func   Function to call when location lookup completes. user   User-defined parameter to pass the function. See also: gale_find_location()

void gale_find_exact_location ( oop_source * oop, struct gale_text, gale_call_location * func, void * user )

Look up a Gale location address without alias expansion. This function is like gale_find_location(), but accepts only canonical location names, and skips all alias expansion steps. Parameters: oop   Liboop event source to use. name   Name of the location to look up (e.g. "pub.food@ofb.net"). func   Function to call when location lookup completes. user   User-defined parameter to pass the function. See also: gale_find_location()

void gale_find_location ( oop_source * oop, struct gale_text, gale_call_location * func, void * user )

Look up a Gale location address. Start looking up a Gale location address in the background and return immediately. When the lookup is complete (whether it succeeded or failed), the supplied callback is invoked. Parameters: oop   Liboop event source to use. name   Name of the location to look up (e.g. "pub.food"). func   Function to call when location lookup completes. user   User-defined parameter to pass the function. See also: gale_location_name(), gale_find_exact_location()

struct gale_key * gale_location_key ( struct gale_location * loc )

Find the key of a location. This function will return the key responsible for controlling a location's behavior. (For example, the key for "pub.food.bitter@ofb.net" might be "pub.*@ofb.net".) Parameters: loc   Location to find key for. Returns: Key.

const struct gale_map * gale_location_members ( struct gale_location * loc )

Get the membership list of a location. Parameters: loc   Location to examine. Returns: A const gale_map associating the names of member locations with the corresponding location objects, or NULL if the location is public.

struct gale_text gale_location_name ( struct gale_location * loc )

Find a location's name. This is approximately the opposite of gale_find_exact_location(). Parameters: loc   Location to examine. Returns: The name of the location (e.g. "pub.food@ofb.net").

int gale_location_receive_ok ( struct gale_location * loc )

Determine if we can receive messages sent to a location. Effectively, this is true if we hold the private key for a location (or the location is public). Parameters: loc   Location to examine. Returns: Nonzero if we can subscribe to this location.

int gale_location_send_ok ( struct gale_location * loc )

Determine if we can send messages to a location. Parameters: loc   Location to examine. Returns: Nonzero if we can send messages to this location.

struct gale_error_queue * gale_make_queue ( oop_source * oop )

Create an error queue object. Parameters: oop   Liboop event source to use. Returns: New error queue object, used to report errors as messages. See also: gale_on_queue(), gale_queue_error

struct gale_server * gale_make_server ( oop_source * source, struct gale_link * l, struct gale_text server, int avoid_local_port )

Connect to a Gale server. Keeps a link connected. Uses link_on_error() to automatically reconnect if the connection is closed. If you use gale_make_server(), you should not use link_on_error(). (Instead, use gale_on_disconnect().) Parameters: oop   Liboop event source to use. link   The gale_link to keep connected. server   The server to connect to. Normally null_text for the default server. avoid_port   Normally zero. Nonzero to avoid connecting to the local host or numerically smaller IP addresses at the specified port. (Used by the server to avoid loops.) Returns: A server handle you can use to disconnect the link later. See also: gale_reopen(), gale_close(), gale_on_connect(), gale_on_disconnect()

void gale_on_connect ( struct gale_server * s, gale_call_connect * f, void * d )

Set a handler to be called when a connection is established. When gale_make_server() is called, the connection process is initiated in the background. When it completes, the function (if any) registered with gale_on_connect() will be called. Henceforth, the function is also called for every successful reconnection (after disconnection). Parameters: serv   The server handle returned by gale_make_server(). func   The function to call when connection succeeds. user   A user-defined parameter. See also: gale_make_server(), gale_call_connect

void gale_on_disconnect ( struct gale_server * s, gale_call_disconnect * f, void * d )

Set a handler to be called when a connection is broken. A connection established by gale_make_server() can be broken by the remote end, by a faulty network, or by gale_close(). In all but the last case, the connection manager will immediately begin a reconnection attempt. In any case, the function (if any) registered with gale_on_disconnect() will be called to let you know. Parameters: serv   The server handle returned by gale_make_server(). func   The function to call when a connection is broken. user   A user-defined parameter. See also: gale_make_server(), gale_close(), gale_call_disconnect

void gale_on_queue ( struct gale_error_queue * queue, gale_call_message * func, void * user )

Set a handler to be called when an error message object is generated. Parameters: queue   Error queue object to monitor. func   The function to call when a new message is generated. user   A user-defined parameter. See also: gale_make_queue(), gale_queue_error

void gale_pack_message ( oop_source * oop, struct gale_message * msg, gale_call_packet * call, void * user )

Pack a Gale message into a raw "packet". Packing may require location lookups, so this function starts the process in the background, using liboop to invoke a callback when the process is complete. Parameters: oop   Liboop event source to use. msg   Message to pack. func   Function to call with packed message. user   User-defined parameter to pass the function. See also: gale_unpack_message(), link_put()

struct gale_text gale_pack_subscriptions ( struct gale_location ** list, int * positive )

Pack a list of locations into a subscription expression. Parameters: list   NULL-terminated array of location pointers. positive   Corresponding array of subscription flags, zero for negative subscriptions and nonzero for positive subscriptions. If positive is NULL, all locations are assumed to be positive. Returns: Raw form of subscription expression. See also: gale_find_location()

void gale_unpack_message ( oop_source * oop, struct gale_packet * pack, gale_call_message * func, void * user )

Unpack a Gale message from a raw "packet". Unpacking may require location lookups, so this function starts the process in the background, using liboop to invoke a callback when the process is complete. Parameters: oop   Liboop event source to use. pack   "Packet" to unpack (usually as received). func   Function to call with unpacked message. user   User-defined parameter to pass the function. See also: gale_pack_message(), link_on_message()

---

Variable Documentation

void * gale_queue_error

Add an error report to an error queue object. Parameters: severity   The severity of the error. msg   The error message. queue   The error queue object. Returns: OOP_CONTINUE. See also: gale_make_queue(), gale_on_queue()

---