prepare_async

Proxy itself does not support any features, but subclasses like Channel can support features, which can either be core functionality like TP_CHANNEL_FEATURE_CORE, or extended functionality like TP_CHANNEL_FEATURE_CHAT_STATES.

Proxy instances start with no features prepared. When features are requested via prepare_async, the proxy starts to do the necessary setup to use those features.

prepare_async always waits for core functionality of the proxy's class to be prepared, even if it is not specifically requested: for instance, because TP_CHANNEL_FEATURE_CORE is core functionality of a Channel,

TpChannel *channel = ...;

tp_proxy_prepare_async (channel, NULL, callback, user_data);

is equivalent to

TpChannel *channel = ...;
GQuark features[] = { TP_CHANNEL_FEATURE_CORE, 0 };

tp_proxy_prepare_async (channel, features, callback, user_data);

If a feature represents core functionality (like TP_CHANNEL_FEATURE_CORE), failure to prepare it will result in prepare_async finishing unsuccessfully: if failure to prepare the feature indicates that the proxy is no longer useful, it will also emit invalidated.

If a feature represents non-essential functionality (like TP_CHANNEL_FEATURE_CHAT_STATES), or is not supported by the object at all, then failure to prepare it is not fatal: prepare_async will complete successfully, but is_prepared will still return false for the feature, and accessor methods for the feature will typically return a dummy value.

Some Proxy subclasses automatically start to prepare their core features when instantiated, and features will sometimes become prepared as a side-effect of other actions, but to ensure that a feature is present you must generally call prepare_async and wait for the result.

Parameters:

this	an instance of a Proxy subclass
features	an array of desired features, ending with 0; null is equivalent to an array containing only 0
callback	if not null, called exactly once, when the features have all been prepared or failed to prepare, or after the proxy is invalidated
user_data	user data for callback