com. kelvinluck. flickr. FlickrClass to provide an interface to the Flickr API This class in combination with FlickrResponseListener provides a convienient way to interact with the Flickr API from AS 2. The implementation should abstract away any processing of XML and allow for type checking in the functions you override in FlickrResponseListener. The idea is to make flash code which interacts with the Flickr API quicker and easier to write. This is still very alpha so feedback is greatfully received :) This code is licensed under a Creative Commons License. http://creativecommons.org/licenses/by-nc-sa/2.0/ UsageVery simple usage example -- in the real world you would either subclass FlickrResponseListener to add functionality you required or override the method you were interested in. import com.kelvinluck.flickr.Flickr;
import com.kelvinluck.flickr.FlickrResponseListener;
var _flickr:Flickr = Flickr.getFlickr();
_flickrResponseListener = new FlickrResponseListener();
_flickr.apiKey = "***";
_flickr.testEcho("one", 2, "free");
This example shows how you would override the method you were interested in: import com.kelvinluck.flickr.Flickr;
import com.kelvinluck.flickr.FlickrResponseListener;
var _flickr:Flickr = Flickr.getFlickr();
_flickrResponseListener = new FlickrResponseListener();
_flickrResponseListener.onTestEcho = function(params:Object) {
// do stuff
}
_flickr.apiKey = "***";
_flickr.testEcho("one", 2, "free");
See AlsoFlickrResponseListener http://www.flickr.com/services/api/ Version0.1.0 AuthorKelvin Luck < kelvin at kelvinluck dot com > Summary | Class to provide an interface to the Flickr API | | | | | | | | | | The place for all API calls to connect to. | | | | | | | | | | | | | | | | The API is already waiting for the response to a method call so cannot make another call | | | | Could not connect to the server (e.g. | | | | The XML returned by the server wasn’t in a <rsp /> tag. | | | | The user wasn’t logged in and tried to access a method that requires authentication (returned from flickr.com) | | The API key sent to flickr was invalid (returned from flickr.com) | | There was no errors and valid XML was returned. | | A constant representing permissions for nobody. | | A constant representing permissions for friends and family. | | A constant representing permissions for contacts. | | A constant representing permissions for everybody. | | | | The email address to use when accessing methods that require user authentication. | | The password to use when accessing methods that require user authentication. | | | | Constructor - as this class implements the Singleton pattern do not call directly but rather access through Flickr.getFlickr. | | Calls flickr.contacts.getList to get a list of contacts for the calling user. | | Calls flickr.contacts.getPublicList to get a list of contacts a user. | | Calls flickr.favorites.add to add a photo to a user’s favorites list. | | Calls flickr.favorites.getList to get a list of the user’s favorite photos. | | Calls flickr.favorites.getPublicList to get a list of favorite public photos for the given user. | | Calls flickr.favorites.remove to remove a photo from a user’s favorites list. | | Calls flickr.people.findByEmail to get a user’s NSID, given their email address. | | Calls flickr.people.findByUsername to get a user’s NSID, given their username. | | Calls flickr.people.getInfo to get information about a user. | | Calls flickr.people.getOnlineList to get a list of all online users. | | Calls flickr.people.getPublicGroups to get the list of public groups a user is a member of. | | Calls flickr.people.getPublicPhotos to get a list of public photos for the given user. | | Calls flickr.photos.addTags to add tags to a given photo. | | Calls flickr.photos.getContactsPhotos to fetch a list of recent photos from the calling users’ contacts. | | Calls flickr.photos.getContactsPublicPhotos to fetch a list of recent public photos from a users’ contacts. | | Calls flickr.photos.getContext to return next and previous photos for a photo in a photostream. | | Calls flickr.photos.getCounts to get a list of photo counts for the given date ranges for the calling user. | | Calls flickr.photos.getExif to return a list of EXIF/TIFF/GPS tags for a given photo. | | Calls flickr.photos.getInfo to get information about a photo.. | | Calls flickr.photos.getNotInSet to get a list of your photos that are not part of any sets. | | Calls flickr.photos.getPerms to get permissions for a photo. | | Calls flickr.photos.getRecent to get a list of the latest public photos uploaded to flickr. | | Calls flickr.photos.getRecent to get the available sizes for a photo. | | Calls flickr.photos.getUntagged to get a list of your photos with no tags. | | Calls flickr.photos.removeTag to remove a tag from a photo. | | Calls flickr.photos.search to get a list of photos matching some criteria. | | Calls flickr.photos.setDates to set one or both of the dates for a photo.. | | Calls flickr.photos.setMeta to set the meta information for a photo. | | Calls flickr.photos.setPerms to set permissions for a photo.. | | Calls flickr.photos.setTags to set the tags for a photo. | | Calls flickr.tags.getListPhoto to get the tag list for a given photo. | | Calls flickr.tags.getListUser to get the tag list for a given user (or the currently logged in user). | | Calls flickr.tags.getListUserPopular to get the popular tags for a given user (or the currently logged in user). | | Calls flickr.tags.getRelated to get a list of tags ‘related’ to the given tag, based on clustered usage analysis. | | Calls flickr.test.echo - forwards any arguments on to the Flickr API | | Calls flickr.test.login - A testing method which checks if the caller is logged in then returns their username. | | Used to call a method on the flickr API. | | Called internally on recepit of a response from a request to the REST_ENDPOINT. | | | | | | | | | | | | Private internal function used to avoid duplicate code to parse “the standard photo list xml” | | Returns a reference to the Flickr instance - if none exists yet then creates one and returns a reference to that. | | | | | | | | |
_flickr| private static var _flickr: Flickr |
apiKeyYour Flickr API Key. None of the method calls will work without this. _apiKey| private var _apiKey: String |
REST_ENDPOINTThe place for all API calls to connect to. The default value of connecting directly to the flickr.com server will only work if a relevant entry is added to their crossdomain.xml file otherwise set the value to the location of a proxy script on your server. _REST_ENDPOINT| private var _REST_ENDPOINT: String |
awaitingResponse| private var awaitingResponse: Boolean |
_restXML| private var _restXML: XML |
_calledMethod| private var _calledMethod: String |
_additionalArgs| private var _additionalArgs: Object |
_email| private var _email: String |
_password| private var _password: String |
STATUS_BUSY| public static var STATUS_BUSY: Number |
The API is already waiting for the response to a method call so cannot make another call STATUS_BUSY_DESCRIPTION| public static var STATUS_BUSY_DESCRIPTION: String |
STATUS_ERROR_CONNECTING| public static var STATUS_ERROR_CONNECTING: Number |
Could not connect to the server (e.g. no internet connection, server down, security restrictions) STATUS_ERROR_CONNECTING_DESCRIPTION| public static var STATUS_ERROR_CONNECTING_DESCRIPTION: String |
STATUS_INVALID_XML| public static var STATUS_INVALID_XML: Number |
The XML returned by the server wasn’t in a <rsp /> tag. STATUS_INVALID_XML_DESCRIPTION| public static var STATUS_INVALID_XML_DESCRIPTION: String |
STATUS_USER_NOT_LOGGED_IN| public static var STATUS_USER_NOT_LOGGED_IN: Number |
The user wasn’t logged in and tried to access a method that requires authentication (returned from flickr.com) STATUS_INVALID_API_KEY| public static var STATUS_INVALID_API_KEY: Number |
The API key sent to flickr was invalid (returned from flickr.com) STATUS_OK| public static var STATUS_OK: Number |
There was no errors and valid XML was returned. PERM_NOBODY| public static var PERM_NOBODY: Number |
A constant representing permissions for nobody. See AlsophotosSetPerms PERM_FRIENDS| public static var PERM_FRIENDS: Number |
A constant representing permissions for friends and family. See AlsophotosSetPerms PERM_CONTACTS| public static var PERM_CONTACTS: Number |
A constant representing permissions for contacts. See AlsophotosSetPerms PERM_EVERYBODY| public static var PERM_EVERYBODY: Number |
A constant representing permissions for everybody. See AlsophotosSetPerms email| public function set email( | email: | String | ):Void |
|
The email address to use when accessing methods that require user authentication. password| public function set password( | password: | String | ):Void |
|
The password to use when accessing methods that require user authentication. Flickr| private function Flickr() |
Constructor - as this class implements the Singleton pattern do not call directly but rather access through Flickr.getFlickr. favoritesAdd| public function favoritesAdd( | photoId: | Number, | | email: | String, | | password: | String | ) |
|
Calls flickr.favorites.add to add a photo to a user’s favorites list. TODODoesn’t currently add the Photo to the Person._favorites Object as we don’t have and actual Person object for the calling user. Is there a way around this? Or maybe we don’t want to do this as the Person._favorites Object isn’t necessarily up to date anyway... Parameters| photoId | The id of the photo you want to add. | | email | The email address of the user whose favourites you want to add to [Optional: default=<email>] | | password | The password of the user whose favourites you want to add to [Optional: default=<password>] |
See AlsoFlickrResponseListener.onFavoritesAdd http://www.flickr.com- /services- /api- /flickr.favorites.add.html favoritesGetList| public function favoritesGetList( | userId: | String, | | perPage: | Number, | | page: | Number, | | email: | String, | | password: | String | ) |
|
Calls flickr.favorites.getList to get a list of the user’s favorite photos. Parameters| userId | The id of the user to get favourites for [Optional: default=logged in user] | | perPage | The number of results to get per page [Optional: default=100] | | page | The page of results to get [Optional: default=1] | | email | The email address of the user whose favourites you want to add to [Optional: default=<email>] | | password | The password of the user whose favourites you want to add to [Optional: default=<password>] |
See AlsoFlickrResponseListener.onFavoritesGetList http://www.flickr.com- /services- /api- /flickr.favorites.getList.html favoritesRemove| public function favoritesRemove( | photoId: | Number, | | email: | String, | | password: | String | ) |
|
Calls flickr.favorites.remove to remove a photo from a user’s favorites list. TODODoesn’t currently remove the Photo from the Person._favorites Object as we don’t have and actual Person object for the calling user. Is there a way around this? Or maybe we don’t want to do this as the Person._favorites Object isn’t necessarily up to date anyway... Parameters| photoId | The id of the photo you want to add. | | email | The email address of the user whose favourites you want to add to [Optional: default=<email>] | | password | The password of the user whose favourites you want to add to [Optional: default=<password>] |
See AlsoFlickrResponseListener.onFavoritesRemove http://www.flickr.com- /services- /api- /flickr.favorites.remove.html photosAddTags| function photosAddTags ( | photoId: | Number, | | tags: | String, | | email: | String, | | password: | String | ) |
|
Calls flickr.photos.addTags to add tags to a given photo. Parameters| photoId | The id of the photo to add tags to. | | tags | The tags to add to the photo. | | email | The email address of the user whose favourites you want to add to [Optional: default=<email>] | | password | The password of the user whose favourites you want to add to [Optional: default=<password>] |
See AlsoFlickrResponseListener.onPhotosAddTags http://flickr.com- /services- /api- /flickr.photos.addTags.html photosGetContactsPhotos| function photosGetContactsPhotos ( | count: | Number, | | justFriends: | Boolean, | | singlePhoto: | Boolean, | | includeSelf: | Boolean, | | email: | String, | | password: | String | ) |
|
Calls flickr.photos.getContactsPhotos to fetch a list of recent photos from the calling users’ contacts. Parameters| count | Number of photos to return. Defaults to 10, maximum 50. This is only used if single_photo is not passed. | | justFriends | set as 1 to only show photos from friends and family (excluding regular contacts). [Optional: default=0]. | | singlePhoto | Only fetch one photo (the latest) per contact, instead of all photos in chronological order [Optional: default=0]. | | includeSelf | Set to 1 to include photos from the calling user. [Optional: default=0]. | | email | The email address of the user whose favourites you want to add to [Optional: default=<email>] | | password | The password of the user whose favourites you want to add to [Optional: default=<password>] |
See AlsoFlickrResponseListener.onPhotosGetContactsPhotos http://flickr.com- /services- /api- /flickr.photos.getContactsPhotos.html photosGetContactsPublicPhotos| function photosGetContactsPublicPhotos ( | nsid: | String, | | count: | Number, | | justFriends: | Boolean, | | singlePhoto: | Boolean, | | includeSelf: | Boolean | ) |
|
Calls flickr.photos.getContactsPublicPhotos to fetch a list of recent public photos from a users’ contacts. Parameters| nsid | The NSID of the user to fetch photos for. | | count | Number of photos to return. Defaults to 10, maximum 50. This is only used if single_photo is not passed. | | justFriends | set as 1 to only show photos from friends and family (excluding regular contacts). [Optional: default=0]. | | singlePhoto | Only fetch one photo (the latest) per contact, instead of all photos in chronological order [Optional: default=0]. | | includeSelf | Set to 1 to include photos from the calling user. [Optional: default=0]. |
See AlsoFlickrResponseListener.onPhotosGetContactsPublicPhotos http://www.flickr.com- /services- /api- /flickr.photos.getContactsPublicPhotos.html photosGetCounts| function photosGetCounts ( | dates: | String, | | takenDates: | String, | | email: | String, | | password: | String | ) |
|
Calls flickr.photos.getCounts to get a list of photo counts for the given date ranges for the calling user. Parameters| dates | A comma delimited list of unix timestamps denoting the periods to return counts for. They should be specified smallest first. [Optional: if not present then takenDates used instead. | | takenDates | A comma delimited list of mysql datetimes denoting the periods to return counts for. They should be specified smallest first. [Optional: if not present then dates used instead. | | email | The email address of the user whose photos you want to count [Optional: default=<email>] | | password | The password of the user whose photos you want to count [Optional: default=<password>] |
Note- The dates parameter is passed as UNIX Timestamps while the takenDates parameter is passed as MySQL Timestamps (e.g. 2005-03-21).
- If you want to pass takenDates then pass “” (empty string) or undefined as the value of dates.
TODOShould we change this method to accept Arrays of Date Objects rather than comma delimited Strings? Then we could sort it making order unimportant and could abstract away the fact that Flickr stores dates uploaded and dates taken in different formats. Maybe it would be better if the methods first two arguments were dates (an Array of Date Objects) and type (Flickr.DATES_UPLOADED or Flickr.DATES_TAKEN)? See AlsoFlickrResponseListener.onPhotosGetCounts http://www.flickr.com- /services- /api- /flickr.photos.getCounts.html photosSearch| function photosSearch ( | params | ) |
|
Calls flickr.photos.search to get a list of photos matching some criteria. You pass an object with one or many of the following attributes... Attributes| user_id | The NSID of the user who’s photo to search. If this parameter isn’t passed then everybody’s public photos will be searched. | | tags | A comma-delimited list of tags. Photos with one or more of the tags listed will be returned. | | tagMode | Either ‘any’ for an OR combination of tags, or ‘all’ for an AND combination. Defaults to ‘any’ if not specified. | | text | A free text search. Photos who’s title, description or tags contain the text will be returned. | | min_upload_date | Minimum upload date. Photos with an upload date greater than or equal to this value will be returned. The date should be in the form of a UNIX timestamp. | | max_upload_date | Maximum upload date. Photos with an upload date less than or equal to this value will be returned. The date should be in the form of a UNIX timestamp. | | min_taken_date | Minimum taken date. Photos with an taken date greater than or equal to this value will be returned. The date should be in the form of a MySQL datetime. | | max_taken_date | Maximum taken date. Photos with an taken date less than or equal to this value will be returned. The date should be in the form of a MySQL datetime. | | license | The license id for photos. | | extras | A comma-delimited list of extra information to fetch for each returned record. Currently supported fields are: license, date_upload, date_taken, owner_name, icon_server | | per_page | Number of photos to return per page. If this argument is ommited, it defaults to 100. The maximum allowed value is 500. | | page | The page of results to return. If this argument is ommited, it defaults to 1. | | sort | The order in which to sort returned photos. Deafults to date-posted-desc. The possible values are: date-posted-asc, date-posted-desc, date-taken-asc and date-taken-desc |
TODOShould probably change it to accept dates as Date Objects... Then you wouldn’t have to worry about what type of date flickr expects for the different arguments. See AlsoFlickrResponseListener.onPhotosSearch http://www.flickr.com- /services- /api- /flickr.photos.search.html photosSetDates| function photosSetDates ( | photoId: | Number, | | datePosted: | Date, | | dateTaken: | Date, | | dateTakenGran: | Number | ) |
|
Calls flickr.photos.setDates to set one or both of the dates for a photo.. All parameters are optional but you must provide either dateTaken or datePosted (or both if you like). Dates are passed as Flash Date Objects so you don’t need to worry about the fact that flickr uses two different formats to represent it’s dates... Parameters| photoId | The id of the photo to edit dates for. | | datePosted | The date the photo was uploaded to flickr. | | dateTaken | The date the photo was taken. | | dateTakenGran | The granularity of the date the photo was taken. |
See AlsoFlickrResponseListener.onPhotosSetDates http://flickr.com- /services- /api- /flickr.photos.setDates.html http://flickr.com/services/api/misc.dates.html callMethod| public function callMethod( | method: | String, | | additionalArguments: | Object, | | requiresAuthentication: | Boolean | ):Void |
|
Used to call a method on the flickr API. When the method returns an onAPIResponse event is broadcast to any registered listeners. You should use the methods above unless you are calling a method on Flickr.com which hasn’t yet been implemented in this API as then you will get argument type checking etc... Parameters| method | The name of the method you want to call | | additionalArguments | Any additional arguments required by the object [Optional] | | requiresAuthentication | Whether the called method requires authentication. if it does and no values for email and password exist within the additionalArguments object then the values Flickr.email and Flickr.password will be used [optional: default=false] |
See alsoFlickr.onAPIResponse onAPIResponse| private function onAPIResponse( | success: | Boolean | ):Void |
|
Called internally on recepit of a response from a request to the REST_ENDPOINT. Interperets the received XML and broadcasts an onAPIResponse event to any registered listeners. If the XML was the result of a known method call then the broadcast event will include sensible information, otherwise it will just be the XML for parsing outside this class (e.g. if a new method has been added to the Flickr.com API and not programmed into this class). Parameters| success | Whether the call to the API was successfull (e.g. the server specfied in REST_ENDPOINT was connected to) or not. |
REST_ENDPOINT| public function set REST_ENDPOINT( | REST_ENDPOINT: | String | ):Void |
|
REST_ENDPOINT| public function get REST_ENDPOINT():String |
apiKey| public function set apiKey( | apiKey: | String | ):Void |
|
_parsePhotoXML| private function _parsePhotoXML( | px: | XMLNode | ):Array |
|
Private internal function used to avoid duplicate code to parse “the standard photo list xml” Params| px | The “standard photo list xml” from flickr. |
ReturnsAn Array of Photo objects. getFlickr| public static function getFlickr():Flickr |
Returns a reference to the Flickr instance - if none exists yet then creates one and returns a reference to that. ReturnsA Flickr instance toString| public function toString():String |
addEventListener| function addEventListener() |
removeEventListener| function removeEventListener() |
|