meanwhile: mw_srvc_aware.h File Reference

# mw_srvc_aware.h File Reference

## Detailed Description

The aware service.

..

Todo:
  remove the whole idea of an instantiated mwAwareList and instead use arbitrary pointers (including NULL) as keys to internally stored lists. This removes the problem of the service free'ing its lists and invalidating mwAwareList references from client code.

`#include "mw_common.h"`

Go to the source code of this file.

## Data Structures
struct | mwAwareHandler
struct | mwAwareListHandler
## Defines
#define | mwService_AWARE 0x00000011
| Type identifier for the aware service.
## Typedefs
typedef void(* | mwAwareAttributeHandler )(struct mwServiceAware *srvc, struct mwAwareAttribute *attrib)
typedef void(* | mwAwareIdAttributeHandler )(struct mwAwareList *list, struct mwAwareIdBlock *id, struct mwAwareAttribute *attrib)
| Appropriate function type for the on-option signal.
typedef void(* | mwAwareSnapshotHandler )(struct mwAwareList *list, struct mwAwareSnapshot *id)
| Appropriate function type for the on-aware signal.
## Enumerations
enum | mwAwareAttributeKeys { mwAttribute_AV_PREFS_SET = 0x01, mwAttribute_MICROPHONE = 0x02, mwAttribute_SPEAKERS = 0x03, mwAttribute_VIDEO_CAMERA = 0x04, mwAttribute_FILE_TRANSFER = 0x06 }
| Predefined keys appropriate for a mwAwareAttribute. More...
## Functions
gboolean | mwAwareAttribute_asBoolean (const struct mwAwareAttribute *attrib)
guint32 | mwAwareAttribute_asInteger (const struct mwAwareAttribute *attrib)
struct mwOpaque * | mwAwareAttribute_asOpaque (const struct mwAwareAttribute *attrib)
| Direct access to an attribute's underlying opaque.
char * | mwAwareAttribute_asString (const struct mwAwareAttribute *attrib)
| Copy of attribute string, must be g_free'd.
guint32 | mwAwareAttribute_getKey (const struct mwAwareAttribute *attrib)
int | mwAwareList_addAware (struct mwAwareList *list, GList *id_list)
| Add a collection of user IDs to an aware list.
void | mwAwareList_free (struct mwAwareList *list)
| Clean and free an aware list.
gpointer | mwAwareList_getClientData (struct mwAwareList *list)
struct mwAwareListHandler * | mwAwareList_getHandler (struct mwAwareList *list)
guint32 * | mwAwareList_getWatchedAttributes (struct mwAwareList *list)
struct mwAwareList * | mwAwareList_new (struct mwServiceAware *srvc, struct mwAwareListHandler *handler)
| Allocate and initialize an aware list.
int | mwAwareList_removeAllAware (struct mwAwareList *list)
int | mwAwareList_removeAware (struct mwAwareList *list, GList *id_list)
| Remove a collection of user IDs from an aware list.
void | mwAwareList_removeClientData (struct mwAwareList *list)
void | mwAwareList_setClientData (struct mwAwareList *list, gpointer data, GDestroyNotify cleanup)
int | mwAwareList_unwatchAllAttributes (struct mwAwareList *list)
| remove all watched attributes
int | mwAwareList_unwatchAttributeArray (struct mwAwareList *list, guint32 *keys)
| stop watching a NULL terminated array of keys
int | mwAwareList_unwatchAttributes (struct mwAwareList *list, guint32 key,...)
| stop watching a NULL terminated list of keys
int | mwAwareList_watchAttributeArray (struct mwAwareList *list, guint32 *keys)
| watch an NULL terminated array of keys
int | mwAwareList_watchAttributes (struct mwAwareList *list, guint32 key,...)
| watch a NULL terminated list of keys
struct mwAwareAttribute * | mwServiceAware_getAttribute (struct mwServiceAware *srvc, struct mwAwareIdBlock *user, guint32 key)
| look up the last known copy of an attribute for a user by the attribute's key
const char * | mwServiceAware_getText (struct mwServiceAware *srvc, struct mwAwareIdBlock *user)
| look up the status description for a user
struct mwServiceAware * | mwServiceAware_new (struct mwSession *session, struct mwAwareHandler *handler)
int | mwServiceAware_setAttribute (struct mwServiceAware *srvc, guint32 key, struct mwOpaque *opaque)
| Set an attribute value for this session.
int | mwServiceAware_setAttributeBoolean (struct mwServiceAware *srvc, guint32 key, gboolean val)
int | mwServiceAware_setAttributeInteger (struct mwServiceAware *srvc, guint32 key, guint32 val)
int | mwServiceAware_setAttributeString (struct mwServiceAware *srvc, guint32 key, const char *str)
void | mwServiceAware_setStatus (struct mwServiceAware *srvc, struct mwAwareIdBlock *user, struct mwUserStatus *stat)
| trigger a got_aware event constructed from the passed user and status information.
int | mwServiceAware_unsetAttribute (struct mwServiceAware *srvc, guint32 key)
| Unset an attribute for this session.

## Define Documentation

#define mwService_AWARE 0x00000011

Type identifier for the aware service.

## Typedef Documentation

typedef void(* mwAwareAttributeHandler)(struct mwServiceAware *srvc, struct mwAwareAttribute *attrib)

typedef void(* mwAwareIdAttributeHandler)(struct mwAwareList *list, struct mwAwareIdBlock *id, struct mwAwareAttribute *attrib)

Appropriate function type for the on-option signal.

The option's value may need to be explicitly loaded in some instances, resulting in this handler being triggered again.

Parameters:

  | list | mwAwareList emiting the signal
  | id | awareness the attribute belongs to
  | attrib | attribute

typedef void(* mwAwareSnapshotHandler)(struct mwAwareList *list, struct mwAwareSnapshot *id)

Appropriate function type for the on-aware signal.

Parameters:

  | list | mwAwareList emiting the signal
  | id | awareness status information
  | data | user-specified data

## Enumeration Type Documentation

enum mwAwareAttributeKeys

Predefined keys appropriate for a mwAwareAttribute.

Enumerator:

  mwAttribute_AV_PREFS_SET | A/V prefs specified, gboolean.
  mwAttribute_MICROPHONE | has a microphone, gboolean
  mwAttribute_SPEAKERS | has speakers, gboolean
  mwAttribute_VIDEO_CAMERA | has a video camera, gboolean
  mwAttribute_FILE_TRANSFER | supports file transfers, gboolean

## Function Documentation

gboolean mwAwareAttribute_asBoolean | ( | const struct mwAwareAttribute * | attrib | ) |

guint32 mwAwareAttribute_asInteger | ( | const struct mwAwareAttribute * | attrib | ) |

struct mwOpaque* mwAwareAttribute_asOpaque | ( | const struct mwAwareAttribute * | attrib | ) | `[read]`

Direct access to an attribute's underlying opaque.

char* mwAwareAttribute_asString | ( | const struct mwAwareAttribute * | attrib | ) |

Copy of attribute string, must be g_free'd.

If the attribute's content cannot be loaded as a string, returns NULL

guint32 mwAwareAttribute_getKey | ( | const struct mwAwareAttribute * | attrib | ) |

int mwAwareList_addAware | ( | struct mwAwareList * | list,
|  | GList * | id_list |
| ) |  |  |

Add a collection of user IDs to an aware list.

Parameters:

  | list | mwAwareList to add user ID to
  | id_list | mwAwareIdBlock list of user IDs to add

Returns:
  0 for success, non-zero to indicate an error.

void mwAwareList_free | ( | struct mwAwareList * | list | ) |

Clean and free an aware list.

gpointer mwAwareList_getClientData | ( | struct mwAwareList * | list | ) |

struct mwAwareListHandler* mwAwareList_getHandler | ( | struct mwAwareList * | list | ) | `[read]`

guint32* mwAwareList_getWatchedAttributes | ( | struct mwAwareList * | list | ) |

struct mwAwareList* mwAwareList_new | ( | struct mwServiceAware * | srvc,
|  | struct mwAwareListHandler * | handler |
| ) |  |  | `[read]`

Allocate and initialize an aware list.

int mwAwareList_removeAllAware | ( | struct mwAwareList * | list | ) |

int mwAwareList_removeAware | ( | struct mwAwareList * | list,
|  | GList * | id_list |
| ) |  |  |

Remove a collection of user IDs from an aware list.

Parameters:

  | list | mwAwareList to remove user ID from
  | id_list | mwAwareIdBlock list of user IDs to remove

Returns:
  0 for success, non-zero to indicate an error.

void mwAwareList_removeClientData | ( | struct mwAwareList * | list | ) |

void mwAwareList_setClientData | ( | struct mwAwareList * | list,
|  | gpointer | data,
|  | GDestroyNotify | cleanup |
| ) |  |  |

int mwAwareList_unwatchAllAttributes | ( | struct mwAwareList * | list | ) |

remove all watched attributes

int mwAwareList_unwatchAttributeArray | ( | struct mwAwareList * | list,
|  | guint32 * | keys |
| ) |  |  |

stop watching a NULL terminated array of keys

int mwAwareList_unwatchAttributes | ( | struct mwAwareList * | list,
|  | guint32 | key,
|  |  | ... |
| ) |  |  |

stop watching a NULL terminated list of keys

int mwAwareList_watchAttributeArray | ( | struct mwAwareList * | list,
|  | guint32 * | keys |
| ) |  |  |

watch an NULL terminated array of keys

int mwAwareList_watchAttributes | ( | struct mwAwareList * | list,
|  | guint32 | key,
|  |  | ... |
| ) |  |  |

watch a NULL terminated list of keys

struct mwAwareAttribute* mwServiceAware_getAttribute | ( | struct mwServiceAware * | srvc,
|  | struct mwAwareIdBlock * | user,
|  | guint32 | key |
| ) |  |  | `[read]`

look up the last known copy of an attribute for a user by the attribute's key

const char* mwServiceAware_getText | ( | struct mwServiceAware * | srvc,
|  | struct mwAwareIdBlock * | user |
| ) |  |  |

look up the status description for a user

struct mwServiceAware* mwServiceAware_new | ( | struct mwSession * | session,
|  | struct mwAwareHandler * | handler |
| ) |  |  | `[read]`

int mwServiceAware_setAttribute | ( | struct mwServiceAware * | srvc,
|  | guint32 | key,
|  | struct mwOpaque * | opaque |
| ) |  |  |

Set an attribute value for this session.

int mwServiceAware_setAttributeBoolean | ( | struct mwServiceAware * | srvc,
|  | guint32 | key,
|  | gboolean | val |
| ) |  |  |

int mwServiceAware_setAttributeInteger | ( | struct mwServiceAware * | srvc,
|  | guint32 | key,
|  | guint32 | val |
| ) |  |  |

int mwServiceAware_setAttributeString | ( | struct mwServiceAware * | srvc,
|  | guint32 | key,
|  | const char * | str |
| ) |  |  |

void mwServiceAware_setStatus | ( | struct mwServiceAware * | srvc,
|  | struct mwAwareIdBlock * | user,
|  | struct mwUserStatus * | stat |
| ) |  |  |

trigger a got_aware event constructed from the passed user and status information.

Useful for adding false users and having the getText function work for them

int mwServiceAware_unsetAttribute | ( | struct mwServiceAware * | srvc,
|  | guint32 | key |
| ) |  |  |

Unset an attribute for this session.