Main Page | Modules | Data Structures | File List | Data Fields | Related Pages

DBusTransport object
[D-BUS internal implementation details]

"Backend" for a DBusConnection. More...

Typedefs

typedef DBusTransport DBusTransport
 Opaque object representing a way message stream.


Functions

dbus_bool_t _dbus_transport_init_base (DBusTransport *transport, const DBusTransportVTable *vtable, dbus_bool_t server, const DBusString *address)
 Initializes the base class members of DBusTransport.

void _dbus_transport_finalize_base (DBusTransport *transport)
 Finalizes base class members of DBusTransport.

DBusTransport_dbus_transport_open (const char *address, DBusError *error)
 Opens a new transport for the given address.

DBusTransport_dbus_transport_ref (DBusTransport *transport)
 Increments the reference count for the transport.

void _dbus_transport_unref (DBusTransport *transport)
 Decrements the reference count for the transport.

void _dbus_transport_disconnect (DBusTransport *transport)
 Closes our end of the connection to a remote application.

dbus_bool_t _dbus_transport_get_is_connected (DBusTransport *transport)
 Returns TRUE if the transport has not been disconnected.

dbus_bool_t _dbus_transport_get_is_authenticated (DBusTransport *transport)
 Returns TRUE if we have been authenticated.

const char * _dbus_transport_get_address (DBusTransport *transport)
 Gets the address of a transport.

dbus_bool_t _dbus_transport_handle_watch (DBusTransport *transport, DBusWatch *watch, unsigned int condition)
 Handles a watch by reading data, writing data, or disconnecting the transport, as appropriate for the given condition.

dbus_bool_t _dbus_transport_set_connection (DBusTransport *transport, DBusConnection *connection)
 Sets the connection using this transport.

void _dbus_transport_messages_pending (DBusTransport *transport, int queue_length)
 Notifies the transport when the outgoing message queue goes from empty to non-empty or vice versa.

dbus_bool_t _dbus_transport_get_unix_fd (DBusTransport *transport, int *fd_p)
 Get the UNIX file descriptor, if any.

void _dbus_transport_do_iteration (DBusTransport *transport, unsigned int flags, int timeout_milliseconds)
 Performs a single poll()/select() on the transport's file descriptors and then reads/writes data as appropriate, queueing incoming messages and sending outgoing messages.

DBusDispatchStatus _dbus_transport_get_dispatch_status (DBusTransport *transport)
 Reports our current dispatch status (whether there's buffered data to be queued as messages, or not, or we need memory).

dbus_bool_t _dbus_transport_queue_messages (DBusTransport *transport)
 Processes data we've read while handling a watch, potentially converting some of it to messages and queueing those messages on the connection.

void _dbus_transport_set_max_message_size (DBusTransport *transport, long size)
 See dbus_connection_set_max_message_size().

long _dbus_transport_get_max_message_size (DBusTransport *transport)
 See dbus_connection_get_max_message_size().

void _dbus_transport_set_max_received_size (DBusTransport *transport, long size)
 See dbus_connection_set_max_received_size().

long _dbus_transport_get_max_received_size (DBusTransport *transport)
 See dbus_connection_get_max_received_size().

dbus_bool_t _dbus_transport_get_unix_user (DBusTransport *transport, unsigned long *uid)
 See dbus_connection_get_unix_user().

dbus_bool_t _dbus_transport_get_unix_process_id (DBusTransport *transport, unsigned long *pid)
 See dbus_connection_get_unix_process_id().

void _dbus_transport_set_unix_user_function (DBusTransport *transport, DBusAllowUnixUserFunction function, void *data, DBusFreeFunction free_data_function, void **old_data, DBusFreeFunction *old_free_data_function)
 See dbus_connection_set_unix_user_function().

dbus_bool_t _dbus_transport_set_auth_mechanisms (DBusTransport *transport, const char **mechanisms)
 Sets the SASL authentication mechanisms supported by this transport.


Detailed Description

"Backend" for a DBusConnection.

Types and functions related to DBusTransport. A transport is an abstraction that can send and receive data via various kinds of network connections or other IPC mechanisms.


Typedef Documentation

DBusTransport
 

Opaque object representing a way message stream.

DBusTransport abstracts various kinds of actual transport mechanism, such as different network protocols, or encryption schemes.

Definition at line 32 of file dbus-transport.h.


Function Documentation

void _dbus_transport_disconnect DBusTransport transport  ) 
 

Closes our end of the connection to a remote application.

Further attempts to use this transport will fail. Only the first call to _dbus_transport_disconnect() will have an effect.

Parameters:
transport the transport.

Definition at line 411 of file dbus-transport.c.

References _dbus_assert, DBusTransportVTable::disconnect, disconnected, NULL, TRUE, and vtable.

Referenced by _dbus_transport_finalize_base(), _dbus_transport_get_is_authenticated(), _dbus_transport_queue_messages(), and dbus_connection_disconnect().

void _dbus_transport_do_iteration DBusTransport transport,
unsigned int  flags,
int  timeout_milliseconds
 

Performs a single poll()/select() on the transport's file descriptors and then reads/writes data as appropriate, queueing incoming messages and sending outgoing messages.

This is the backend for _dbus_connection_do_iteration(). See _dbus_connection_do_iteration() for full details.

Parameters:
transport the transport.
flags indicates whether to read or write, and whether to block.
timeout_milliseconds if blocking, timeout or -1 for no timeout.

Definition at line 680 of file dbus-transport.c.

References _dbus_assert, _dbus_transport_ref(), _dbus_transport_unref(), disconnected, DBusTransportVTable::do_iteration, NULL, and vtable.

Referenced by _dbus_connection_do_iteration().

void _dbus_transport_finalize_base DBusTransport transport  ) 
 

Finalizes base class members of DBusTransport.

Chained up to from subclass finalizers.

Parameters:
transport the transport.

Definition at line 182 of file dbus-transport.c.

References _dbus_auth_unref(), _dbus_counter_set_notify(), _dbus_counter_unref(), _dbus_message_loader_unref(), _dbus_transport_disconnect(), address, auth, dbus_free(), disconnected, free_unix_user_data, live_messages_size, loader, NULL, and unix_user_data.

const char* _dbus_transport_get_address DBusTransport transport  ) 
 

Gets the address of a transport.

It will be NULL for a server-side transport.

Parameters:
transport the transport
Returns:
transport's address

Definition at line 544 of file dbus-transport.c.

References address.

DBusDispatchStatus _dbus_transport_get_dispatch_status DBusTransport transport  ) 
 

Reports our current dispatch status (whether there's buffered data to be queued as messages, or not, or we need memory).

Parameters:
transport the transport
Returns:
current status

Definition at line 799 of file dbus-transport.c.

References _dbus_auth_do_work(), _dbus_counter_get_value(), _dbus_message_loader_peek_message(), _dbus_message_loader_queue_messages(), _dbus_transport_get_is_authenticated(), auth, live_messages_size, loader, max_live_messages_size, NULL, TRUE, and unused_bytes_recovered.

Referenced by _dbus_transport_queue_messages().

dbus_bool_t _dbus_transport_get_is_authenticated DBusTransport transport  ) 
 

Returns TRUE if we have been authenticated.

Will return TRUE even if the transport is disconnected.

Todo:
needs to drop connection->mutex when calling the unix_user_function
Parameters:
transport the transport
Returns:
whether we're authenticated

Definition at line 447 of file dbus-transport.c.

References _dbus_auth_do_work(), _dbus_auth_get_identity(), _dbus_credentials_from_current_process(), _dbus_credentials_match(), _dbus_transport_disconnect(), auth, authenticated, connection, dbus_bool_t, disconnected, FALSE, is_server, NULL, receive_credentials_pending, send_credentials_pending, TRUE, DBusCredentials::uid, unix_user_data, and unix_user_function.

Referenced by _dbus_connection_message_sent(), _dbus_connection_queue_received_message_link(), _dbus_transport_get_dispatch_status(), dbus_connection_get_is_authenticated(), dbus_connection_get_unix_process_id(), and dbus_connection_get_unix_user().

dbus_bool_t _dbus_transport_get_is_connected DBusTransport transport  ) 
 

Returns TRUE if the transport has not been disconnected.

Disconnection can result from _dbus_transport_disconnect() or because the server drops its end of the connection.

Parameters:
transport the transport.
Returns:
whether we're connected

Definition at line 432 of file dbus-transport.c.

References disconnected.

long _dbus_transport_get_max_message_size DBusTransport transport  ) 
 

See dbus_connection_get_max_message_size().

Parameters:
transport the transport
Returns:
max message size

Definition at line 902 of file dbus-transport.c.

References _dbus_message_loader_get_max_message_size(), and loader.

Referenced by dbus_connection_get_max_message_size().

long _dbus_transport_get_max_received_size DBusTransport transport  ) 
 

See dbus_connection_get_max_received_size().

Parameters:
transport the transport
Returns:
max bytes for all live messages

Definition at line 932 of file dbus-transport.c.

References max_live_messages_size.

Referenced by dbus_connection_get_max_received_size().

dbus_bool_t _dbus_transport_get_unix_fd DBusTransport transport,
int *  fd_p
 

Get the UNIX file descriptor, if any.

Parameters:
transport the transport
fd_p pointer to fill in with the descriptor
Returns:
TRUE if a descriptor was available

Definition at line 647 of file dbus-transport.c.

References _dbus_transport_ref(), _dbus_transport_unref(), dbus_bool_t, disconnected, FALSE, DBusTransportVTable::get_unix_fd, NULL, and vtable.

Referenced by dbus_connection_get_unix_fd().

dbus_bool_t _dbus_transport_get_unix_process_id DBusTransport transport,
unsigned long *  pid
 

See dbus_connection_get_unix_process_id().

Parameters:
transport the transport
pid return location for the process ID
Returns:
TRUE if uid is filled in with a valid process ID

Definition at line 977 of file dbus-transport.c.

References _dbus_auth_get_identity(), auth, authenticated, FALSE, DBusCredentials::pid, and TRUE.

Referenced by dbus_connection_get_unix_process_id().

dbus_bool_t _dbus_transport_get_unix_user DBusTransport transport,
unsigned long *  uid
 

See dbus_connection_get_unix_user().

Parameters:
transport the transport
uid return location for the user ID
Returns:
TRUE if uid is filled in with a valid user ID

Definition at line 945 of file dbus-transport.c.

References _dbus_auth_get_identity(), _DBUS_INT_MAX, auth, authenticated, FALSE, TRUE, and DBusCredentials::uid.

Referenced by dbus_connection_get_unix_user().

dbus_bool_t _dbus_transport_handle_watch DBusTransport transport,
DBusWatch watch,
unsigned int  condition
 

Handles a watch by reading data, writing data, or disconnecting the transport, as appropriate for the given condition.

Parameters:
transport the transport.
watch the watch.
condition the current state of the watched file descriptor.
Returns:
FALSE if not enough memory to fully handle the watch

Definition at line 559 of file dbus-transport.c.

References _dbus_assert, _dbus_transport_ref(), _dbus_transport_unref(), _dbus_warn(), _dbus_watch_ref(), _dbus_watch_sanitize_condition(), _dbus_watch_unref(), dbus_bool_t, dbus_watch_get_fd(), disconnected, DBusTransportVTable::handle_watch, NULL, TRUE, and vtable.

Referenced by _dbus_connection_handle_watch().

dbus_bool_t _dbus_transport_init_base DBusTransport transport,
const DBusTransportVTable vtable,
dbus_bool_t  server,
const DBusString address
 

Initializes the base class members of DBusTransport.

Chained up to by subclasses in their constructor.

Parameters:
transport the transport being created.
vtable the subclass vtable.
server TRUE if this transport is on the server side of a connection
address the address of the transport
Returns:
TRUE on success.

Definition at line 88 of file dbus-transport.c.

References _dbus_assert, _dbus_auth_client_new(), _dbus_auth_server_new(), _dbus_auth_unref(), _dbus_counter_new(), _dbus_counter_set_notify(), _dbus_counter_unref(), _dbus_message_loader_new(), _dbus_message_loader_unref(), _dbus_string_copy_data(), address, auth, authenticated, credentials, disconnected, FALSE, free_unix_user_data, DBusCredentials::gid, is_server, live_messages_size, loader, max_live_messages_size, messages_need_sending, NULL, DBusCredentials::pid, receive_credentials_pending, refcount, send_credentials_pending, TRUE, DBusCredentials::uid, unix_user_data, unix_user_function, and vtable.

Referenced by _dbus_transport_new_for_fd().

void _dbus_transport_messages_pending DBusTransport transport,
int  queue_length
 

Notifies the transport when the outgoing message queue goes from empty to non-empty or vice versa.

Typically causes the transport to add or remove its DBUS_WATCH_WRITABLE watch.

Parameters:
transport the transport.
queue_length the length of the outgoing message queue.

Definition at line 623 of file dbus-transport.c.

References _dbus_assert, _dbus_transport_ref(), _dbus_transport_unref(), disconnected, messages_need_sending, DBusTransportVTable::messages_pending, NULL, and vtable.

Referenced by _dbus_connection_message_sent().

DBusTransport* _dbus_transport_open const char *  address,
DBusError error
 

Opens a new transport for the given address.

(This opens a client-side-of-the-connection transport.)

Todo:
error messages on bad address could really be better. DBusResultCode is a bit limiting here.
Parameters:
address the address.
error location to store reason for failure.
Returns:
new transport of NULL on failure.

Definition at line 210 of file dbus-transport.c.

References _dbus_string_free(), _dbus_string_init_const(), _dbus_string_parse_int(), _dbus_transport_new_for_domain_socket(), _dbus_transport_new_for_tcp_socket(), dbus_address_entries_free(), dbus_address_entry_get_method(), dbus_address_entry_get_value(), dbus_bool_t, dbus_error_free(), dbus_error_init(), dbus_move_error(), dbus_parse_address(), dbus_set_error(), FALSE, NULL, and TRUE.

Referenced by dbus_connection_open().

dbus_bool_t _dbus_transport_queue_messages DBusTransport transport  ) 
 

Processes data we've read while handling a watch, potentially converting some of it to messages and queueing those messages on the connection.

Parameters:
transport the transport
Returns:
TRUE if we had enough memory to queue all messages

Definition at line 837 of file dbus-transport.c.

References _dbus_assert, _dbus_connection_queue_received_message_link(), _dbus_message_add_size_counter(), _dbus_message_loader_get_is_corrupted(), _dbus_message_loader_pop_message_link(), _dbus_message_loader_putback_message_link(), _dbus_transport_disconnect(), _dbus_transport_get_dispatch_status(), connection, DBusList::data, live_messages_size, loader, and NULL.

DBusTransport* _dbus_transport_ref DBusTransport transport  ) 
 

Increments the reference count for the transport.

Parameters:
transport the transport.
Returns:
the transport.

Definition at line 371 of file dbus-transport.c.

References _dbus_assert, and refcount.

Referenced by _dbus_connection_new_for_transport(), _dbus_transport_do_iteration(), _dbus_transport_get_unix_fd(), _dbus_transport_handle_watch(), _dbus_transport_messages_pending(), and _dbus_transport_set_connection().

dbus_bool_t _dbus_transport_set_auth_mechanisms DBusTransport transport,
const char **  mechanisms
 

Sets the SASL authentication mechanisms supported by this transport.

Parameters:
transport the transport
mechanisms the NULL-terminated array of mechanisms
Returns:
FALSE if no memory

Definition at line 1036 of file dbus-transport.c.

References _dbus_auth_set_mechanisms(), and auth.

dbus_bool_t _dbus_transport_set_connection DBusTransport transport,
DBusConnection connection
 

Sets the connection using this transport.

Allows the transport to add watches to the connection, queue incoming messages, and pull outgoing messages.

Parameters:
transport the transport.
connection the connection.
Returns:
FALSE if not enough memory

Definition at line 597 of file dbus-transport.c.

References _dbus_assert, _dbus_transport_ref(), _dbus_transport_unref(), connection, DBusTransportVTable::connection_set, NULL, and vtable.

Referenced by _dbus_connection_new_for_transport().

void _dbus_transport_set_max_message_size DBusTransport transport,
long  size
 

See dbus_connection_set_max_message_size().

Parameters:
transport the transport
size the max size of a single message

Definition at line 889 of file dbus-transport.c.

References _dbus_message_loader_set_max_message_size(), and loader.

Referenced by dbus_connection_set_max_message_size().

void _dbus_transport_set_max_received_size DBusTransport transport,
long  size
 

See dbus_connection_set_max_received_size().

Parameters:
transport the transport
size the max size of all incoming messages

Definition at line 914 of file dbus-transport.c.

References _dbus_counter_set_notify(), live_messages_size, and max_live_messages_size.

Referenced by dbus_connection_set_max_received_size().

void _dbus_transport_set_unix_user_function DBusTransport transport,
DBusAllowUnixUserFunction  function,
void *  data,
DBusFreeFunction  free_data_function,
void **  old_data,
DBusFreeFunction old_free_data_function
 

See dbus_connection_set_unix_user_function().

Parameters:
transport the transport
function the predicate
data data to pass to the predicate
free_data_function function to free the data
old_data the old user data to be freed
old_free_data_function old free data function to free it with

Definition at line 1012 of file dbus-transport.c.

References free_unix_user_data, unix_user_data, and unix_user_function.

Referenced by dbus_connection_set_unix_user_function().

void _dbus_transport_unref DBusTransport transport  ) 
 

Decrements the reference count for the transport.

Disconnects and finalizes the transport if the reference count reaches zero.

Parameters:
transport the transport.

Definition at line 388 of file dbus-transport.c.

References _dbus_assert, DBusTransportVTable::finalize, NULL, refcount, and vtable.

Referenced by _dbus_transport_do_iteration(), _dbus_transport_get_unix_fd(), _dbus_transport_handle_watch(), _dbus_transport_messages_pending(), _dbus_transport_set_connection(), and dbus_connection_open().


Generated on Tue Oct 12 02:07:55 2004 for D-BUS by doxygen 1.3.7