section-group: Flickcurl Flickr API Manual

section-group

Functions

void	flickcurl_free_group ()
void	flickcurl_free_groups ()
flickcurl_category *	flickcurl_groups_browse ()
flickcurl_group *	flickcurl_groups_getInfo ()
int	flickcurl_groups_join ()
int	flickcurl_groups_joinRequest ()
int	flickcurl_groups_leave ()
void	flickcurl_free_member ()
void	flickcurl_free_members ()
flickcurl_member **	flickcurl_groups_members_getList ()
int	flickcurl_groups_pools_add ()
flickcurl_context **	flickcurl_groups_pools_getContext ()
flickcurl_group **	flickcurl_groups_pools_getGroups ()
flickcurl_photo **	flickcurl_groups_pools_getPhotos ()
flickcurl_photos_list *	flickcurl_groups_pools_getPhotos_params ()
int	flickcurl_groups_pools_remove ()
flickcurl_group **	flickcurl_groups_search ()

Types and Values

	flickcurl_group
	flickcurl_member

Description

Functions

flickcurl_free_group ()

void
flickcurl_free_group (flickcurl_group *group);

Destructor for group object

Parameters

group

group object

flickcurl_free_groups ()

void
flickcurl_free_groups (flickcurl_group **groups_object);

Destructor for array of group object

Parameters

groups_object

group object array

flickcurl_groups_browse ()

flickcurl_category *
flickcurl_groups_browse (flickcurl *fc,
                         int cat_id);

Browse the group category tree, finding groups and sub-categories.

Implements flickr.groups.browse (0.13)

Parameters

fc	flickcurl context
cat_id	The category id to fetch a list of groups and sub-categories for. If not specified, it defaults to zero, the root of the category tree. (or NULL)

Returns

non-0 on failure

flickcurl_groups_getInfo ()

flickcurl_group *
flickcurl_groups_getInfo (flickcurl *fc,
                          const char *group_id,
                          const char *lang);

Get information about a group.

Implements flickr.groups.getInfo (0.13)

Parameters

fc	flickcurl context
group_id	The NSID of the group to fetch information for.
lang	The language of the group name and description to fetch. If the language is not found, the primary language of the group will be returned (or NULL)

Returns

non-0 on failure

flickcurl_groups_join ()

int
flickcurl_groups_join (flickcurl *fc,
                       const char *group_id,
                       const char *accept_rules);

Join a public group as a member.

Implements flickr.groups.join (1.25)

Parameters

fc	flickcurl context
group_id	The NSID of the Group in question
accept_rules	If the group has rules, they must be displayed to the user prior to joining. Passing a true value for this argument specifies that the application has displayed the group rules to the user, and that the user has agreed to them. (See flickr.groups.getInfo). Probably takes a '1' or '0' value (or NULL)

Returns

non-0 on failure

flickcurl_groups_joinRequest ()

int
flickcurl_groups_joinRequest (flickcurl *fc,
                              const char *group_id,
                              const char *message,
                              const char *accept_rules);

Request to join a group that is invitation-only.

Implements flickr.groups.joinRequest (1.25)

Parameters

fc	flickcurl context
group_id	The NSID of the group to request joining.
message	Message to the administrators.
accept_rules	If the group has rules, they must be displayed to the user prior to joining. Passing a true value for this argument specifies that the application has displayed the group rules to the user, and that the user has agreed to them. (See flickr.groups.getInfo). Probably takes a '1' or '0' value.

Returns

non-0 on failure

flickcurl_groups_leave ()

int
flickcurl_groups_leave (flickcurl *fc,
                        const char *group_id,
                        const char *delete_photos);

Leave a group.

If the user is the only administrator left, and there are other members, the oldest member will be promoted to administrator.

If the user is the last person in the group, the group will be deleted.

Implements flickr.groups.leave (1.25)

Parameters

fc	flickcurl context
group_id	The NSID of the Group to leave
delete_photos	Delete all photos by this user from the group. Probably takes a '1' or '0' value (or NULL)

Returns

non-0 on failure

flickcurl_free_member ()

void
flickcurl_free_member (flickcurl_member *member_object);

Destructor for member object

Parameters

member_object

member object

flickcurl_free_members ()

void
flickcurl_free_members (flickcurl_member **members_object);

Destructor for array of member object

Parameters

members_object

member object array

flickcurl_groups_members_getList ()

flickcurl_member **
flickcurl_groups_members_getList (flickcurl *fc,
                                  const char *group_id,
                                  const char *membertypes,
                                  int per_page,
                                  int page);

Get a list of the members of a group.

The call must be signed on behalf of a Flickr member, and the ability to see the group membership will be determined by the Flickr member's group privileges.

Implements flickr.groups.members.getList (1.9) as announced as an experimental API on 2009-02-24: http://tech.groups.yahoo.com/group/yws-flickr/message/4749

Parameters

fc	flickcurl context
group_id	Return a list of members for this group. The group must be viewable by the Flickr member on whose behalf the API call is made.
membertypes	Comma separated list of member types: 2: member, 3: moderator 4: admin. By default returns all types. (Returning super rare member type "1: narwhal" isn't supported by this API method) (or NULL)
per_page	Number of members to return per page. If this argument is omitted, it defaults to 100. The maximum allowed value is 500 (or < 0)
page	The page of results to return. If this argument is omitted, it defaults to 1 (or < 0)

Returns

list of members or NULL on failure

flickcurl_groups_pools_add ()

int
flickcurl_groups_pools_add (flickcurl *fc,
                            const char *photo_id,
                            const char *group_id);

Add a photo to a group's pool.

Implements flickr.groups.pools.add (0.12)

Parameters

fc	flickcurl context
photo_id	The id of the photo to add to the group pool.
group_id	The NSID of the group who's pool the photo is to be added to.

Returns

non-0 on failure

flickcurl_groups_pools_getContext ()

flickcurl_context **
flickcurl_groups_pools_getContext (flickcurl *fc,
                                   const char *photo_id,
                                   const char *group_id);

Get next and previous photos for a photo in a group pool.

Implements flickr.groups.pools.getContext (0.7)

Parameters

fc	flickcurl context
photo_id	photo ID
group_id	group ID

Returns

an array of size 3 [prev, next, NULL] flickcurl_context* or NULL on error

flickcurl_groups_pools_getGroups ()

flickcurl_group **
flickcurl_groups_pools_getGroups (flickcurl *fc,
                                  int page,
                                  int per_page);

Returns a list of groups to which you can add photos.

Implements flickr.groups.pools.getGroups (0.12)

Parameters

fc	flickcurl context
per_page	Number of groups to return per page (default 400, max 400)
page	The page of results to return (default 1)

Returns

non-0 on failure

flickcurl_groups_pools_getPhotos ()

flickcurl_photo **
flickcurl_groups_pools_getPhotos (flickcurl *fc,
                                  const char *group_id,
                                  const char *tags,
                                  const char *user_id,
                                  const char *extras,
                                  int per_page,
                                  int page);

Returns a list of pool photos for a given group.

See flickcurl_groups_pools_getPhotos_params() for details of the fields.

Implements flickr.groups.pools.getPhotos (0.12)

Parameters

fc	flickcurl context
group_id	The id of the group who's pool you which to get the photo list for.
tags	A tag to filter the pool with. At the moment only one tag at a time is supported. (or NULL)
user_id	The nsid of a user (or NULL). If given, retrieves only photos that the user has contributed to the group pool.
extras	A comma-delimited list of extra information to fetch for each returned record (or NULL)
per_page	Number of photos to return per page (default 100, max 500)
page	The page of results to return (default 1)

Returns

non-0 on failure

flickcurl_groups_pools_getPhotos_params ()

flickcurl_photos_list *
flickcurl_groups_pools_getPhotos_params
                               (flickcurl *fc,
                                const char *group_id,
                                const char *tags,
                                const char *user_id,
                                flickcurl_photos_list_params *list_params);

Returns a list of pool photos for a given group.

Currently supported extra fields are: license, date_upload, date_taken, owner_name, icon_server, original_format, last_update, geo, tags, machine_tags.

Optional extra type 'media' that will return an extra media = VALUE for VALUE "photo" or "video". API addition 2008-04-07.

Parameters

fc	flickcurl context
group_id	The id of the group who's pool you which to get the photo list for.
tags	A tag to filter the pool with. At the moment only one tag at a time is supported. (or NULL)
user_id	The nsid of a user (or NULL). If given, retrieves only photos that the user has contributed to the group pool.
list_params	flickcurl_photos_list_params result parameters (or NULL)

Returns

non-0 on failure

flickcurl_groups_pools_remove ()

int
flickcurl_groups_pools_remove (flickcurl *fc,
                               const char *photo_id,
                               const char *group_id);

Remove a photo from a group pool.

Implements flickr.groups.pools.remove (0.12)

Parameters

fc	flickcurl context
photo_id	The id of the photo to remove from the group pool.
group_id	The NSID of the group who's pool the photo is to removed from.

Returns

non-0 on failure

flickcurl_groups_search ()

flickcurl_group **
flickcurl_groups_search (flickcurl *fc,
                         const char *text,
                         int per_page,
                         int page);

Search for groups. 18+ groups will only be returned for authenticated calls where the authenticated user is over 18.

Implements flickr.groups.search (0.13)

Parameters

fc	flickcurl context
text	The text to search for.
per_page	Number of groups to return per page, default 100, max 500 (or NULL)
page	The page of results to return, default 1 (or NULL)

Returns

non-0 on failure

Types and Values

flickcurl_group

typedef struct {
  char* nsid;
  char* name;
  char* description;
  char* lang;
  int is_admin;
  int is_pool_moderated;
  int is_eighteenplus;
  int privacy;
  int photos;
  int iconserver;
  int members;
  int throttle_count;
  char* throttle_mode;
  int throttle_remaining;
  int iconfarm;
  int is_moderator;
  int is_member;
  char* rules;
  int pool_count;
  int topic_count;
  int photos_ok;
  int videos_ok;
  int images_ok;
  int screens_ok;
  int art_ok;
  int safe_ok;
  int moderate_ok;
  int restricted_ok;
  int has_geo;
} flickcurl_group;

A group.

Members

char *`nsid`;	NSID
char *`name`;	Group Name
char *`description`;	Description
char *`lang`;	Language
int `is_admin`;	user is a group admin
int `is_pool_moderated`;	is the pool moderated
int `is_eighteenplus`;	NOT USED (will always be 0)
int `privacy`;	privacy level
int `photos`;	photos in group count
int `iconserver`;	icon server ID
int `members`;	member count
int `throttle_count`;	throttle count
char *`throttle_mode`;	throttle mode (day, ...)
int `throttle_remaining`;	throttle remaining
int `iconfarm`;	icon farm ID
int `is_moderator`;	user is a moderator
int `is_member`;	user is a member
char *`rules`;	group rules
int `pool_count`;	pool count
int `topic_count`;	topic count
int `photos_ok`;	photos are ok
int `videos_ok`;	videos are ok
int `images_ok`;	images are ok
int `screens_ok`;	screens are ok
int `art_ok`;	art is ok
int `safe_ok`;	safe content is ok
int `moderate_ok`;	moderate content is ok
int `restricted_ok`;	restricted content is ok
int `has_geo`;	has geolocation

flickcurl_member

typedef struct {
  char *nsid;
  char *username;
  int iconserver;
  int iconfarm;
  int member_type;
} flickcurl_member;

Member in a group

Members

char *`nsid`;	NSID
char *`username`;	User name
int `iconserver`;	icon server
int `iconfarm`;	icon farm
int `member_type`;	member type - 1: narwhal, 2: member, 3: moderator 4: admin