DBusTransport object
[D-Bus secret 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, const DBusString *server_guid, 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 (DBusAddressEntry *entry, DBusError *error)
 Try to open a new transport for the given address entry.
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.
dbus_bool_t _dbus_transport_get_socket_fd (DBusTransport *transport, int *fd_p)
 Get the socket 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 33 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 451 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(), and _dbus_transport_queue_messages().

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 761 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_unlocked().

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 187 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, expected_guid, 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 651 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 882 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(), DBUS_DISPATCH_COMPLETE, DBUS_DISPATCH_DATA_REMAINS, DBUS_DISPATCH_NEED_MEMORY, live_messages_size, max_live_messages_size, NULL, and TRUE.

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:
we drop connection->mutex when calling the unix_user_function, which may not be safe really.
Parameters:
transport the transport
Returns:
whether we're authenticated

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

References _dbus_assert, _dbus_auth_do_work(), _dbus_auth_get_guid_from_server(), _dbus_auth_get_identity(), _dbus_connection_lock(), _dbus_connection_ref_unlocked(), _dbus_connection_unlock(), _dbus_connection_unref_unlocked(), _dbus_credentials_from_current_process(), _dbus_credentials_match(), _dbus_strdup(), _dbus_transport_disconnect(), auth, authenticated, connection, DBUS_UID_FORMAT, disconnected, expected_guid, FALSE, is_server, NULL, receive_credentials_pending, send_credentials_pending, TRUE, DBusCredentials::uid, unix_user_data, and unix_user_function.

Referenced by _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 476 of file dbus-transport.c.

References disconnected.

Referenced by dbus_connection_unref().

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 985 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 1015 of file dbus-transport.c.

References max_live_messages_size.

Referenced by dbus_connection_get_max_received_size().

dbus_bool_t _dbus_transport_get_socket_fd ( DBusTransport *  transport,
int *  fd_p 
)

Get the socket 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 728 of file dbus-transport.c.

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

Referenced by dbus_connection_get_socket().

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 1060 of file dbus-transport.c.

References _dbus_auth_get_identity(), auth, authenticated, DBUS_PID_UNSET, 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 1028 of file dbus-transport.c.

References _dbus_auth_get_identity(), _DBUS_INT32_MAX, auth, authenticated, DBUS_UID_UNSET, 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 666 of file dbus-transport.c.

References _dbus_assert, _dbus_transport_ref(), _dbus_transport_unref(), _dbus_warn_check_failed(), _dbus_watch_ref(), _dbus_watch_sanitize_condition(), _dbus_watch_unref(), 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,
const DBusString *  server_guid,
const DBusString *  address 
)

Initializes the base class members of DBusTransport.

Chained up to by subclasses in their constructor. The server GUID is the globally unique ID for the server creating this connection and will be NULL for the client side of a connection. The GUID is in hex format.

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

Definition at line 92 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, expected_guid, FALSE, free_unix_user_data, DBusCredentials::gid, is_server, live_messages_size, loader, max_live_messages_size, 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_socket().

DBusTransport* _dbus_transport_open ( DBusAddressEntry *  entry,
DBusError *  error 
)

Try to open a new transport for the given address entry.

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

Parameters:
entry the address entry
error location to store reason for failure.
Returns:
new transport of NULL on failure.

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

References _DBUS_N_ELEMENTS, _dbus_set_bad_address(), _dbus_strdup(), dbus_address_entry_get_value(), dbus_error_init(), dbus_error_is_set(), dbus_free(), dbus_move_error(), expected_guid, and NULL.

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 920 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(), DBusList::data, DBUS_DISPATCH_DATA_REMAINS, DBUS_DISPATCH_NEED_MEMORY, 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 409 of file dbus-transport.c.

References _dbus_assert, and refcount.

Referenced by _dbus_connection_new_for_transport(), _dbus_transport_do_iteration(), _dbus_transport_get_socket_fd(), _dbus_transport_handle_watch(), 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 1119 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 704 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 972 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 997 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 1095 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 426 of file dbus-transport.c.

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

Referenced by _dbus_transport_do_iteration(), _dbus_transport_get_socket_fd(), _dbus_transport_handle_watch(), and _dbus_transport_set_connection().

Generated on Fri Sep 21 18:12:15 2007 for D-Bus by  doxygen 1.5.1