A number designated to represeting the AuthSub method for Authorizing an object.

There is no significance to the number assigned to this variable.

• access: public

The base for queries that use the "entry" path instead of the "feed" path. It's not clear what differentiates this path from the path in Picasa::$BASE_QUERY_URL, but the documentation makes it clear when each is necessary.

• access: protected

The base for a standard query. All non-authenticated queries begin with this string.

• access: protected

The title of the cookie to use when setting and retrieving an Client Login token from a user's Cookies.

• access: public

A token supplied by Google after a successful attempt to authorize this object.

The Auth Token is like a Golden Ticket for doing operations that require authorization.

• access: private

An array that is in an acceptable format for the php function stream_context_create() to create a context.

For an authorized instance, this array holds the HTTP header with the authorization information necessary to make authenticated requests. It is useful to have because it holds both the authorization token as well as the authorization type in the same object.

• link: http://www.php.net/stream_context_create
• access: private

Constructs a string of optional query parameters for requesting a feed from Picasa.

All parameters are optional, their defaults are all null. Passing a null value for a parameter will exclude the value from the parameter list.

• return: A string with optional query parameters strung together with ampersands.
• access: protected

• int $maxResults: The maximum number of results to return.
• int $startIndex: The first element number with the search results to return. Useful for pagination.
• string $keywords: Space-delimited list of keywords to search for.
• string $tags: Space-delimited list of tags to search for.
• string $visibility: Restrict the search to comments in images with the access rights specified here.
• int $thumbsize: Comma-delimited list of thumbnail sizes to fetch.
• int $imgmax: Size of image to return in the $content field of the Picasa_Image field.
• string $location: Named location to search for photos in. For example, London.
• string $sortDescending: Whether or not to sort the items returned by date added descending.
• string $boundingBox: Geo coordinates to search for photos within in the order west, south, east, north.

Generates the XML necessary for creating a Picasa image.

• return: XML that can be sent to Picasa to create an image.
• access: protected

• string $title: The title that the image will be given.
• string $summary: A summary of what is in the image. Optional, the default is an empty string.
• string $keywords: A comma-delimited list of keywords associated with the image. Optional, the default is null.
• string $commentingEnabled: Set to true if other users should be able to comment on the image and false if they shouldn't. Optional, the default is true.
• string $timestamp: The number of miliseconds after the Unix epoch (January 1st, 1970) that the image was taken (roughly).
• string $gmlPosition: The location in the world that this image was taken. The format is latitude and longitude, separated by a space. Optional, the default is null.

Matches the supplied $buf contents against several different HTTP response codes to determine what kind of Picasa_Exception to return.

Note that this does not actually throw an exception, it just determines what kind of exception could be thrown based on the response. It's up to the caller to actually throw the exception.

The name of this method is a little misleading; the response does not need to be from a POST, it can be a response from any kind of request.

• return: A type of Picasa_Exception depending on what response code was found. If the response code is not recognized, then a Picasa_Exception itself is thrown.
• access: public

• string $buf: The HTTP response to check for the response code in.
• string $message: The message to set in the exception. Optional, the default is null. If null is supplied, a default message will be set based on what type of response code is sent.

Looks in the supplied response for the supplied key and finds the value associated with the key if one exists.

Searches between the supplied key and the first linebreak. The value searched for cannot have a linebreak in it.

• return: The value associated with the key. The value will be the string between the key with an equals sign next to it, and the end of the line. Returns null if no value is found.
• access: protected

• string $response: The haystack to look for the key in.
• string $key: The needle to look for in the haystack.

Redirects the user to Google's AuthSub login page so that they can login to access restricted functions.

The URL in the $next parameter must be registered with Google. At the URL specified there, the "token" value must be pulled from the request and passed to {@see Picasa::authorizeWithAuthSub()} for the authorization to be complete.

• access: public

• string $next: The URL that the user should be redirected to after visiting the login page. This URL must be registered with Google in advance. See http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html.
• int $session: Must be either 1 or 0. This indicates if the login should be transferable to a session token, which is valid for a long time, wherease the default token is only useable once.
  1. to enable session tokens, 0 to disable.

Fetches the authorization token from the user's cookies- if one exists- and logs the user in using the retrieved token.

It automatically determines which type of authorization (AuthSub or Client Login) to use based on the type of cookie that is retrieved. If both types exist in the users' cookies, the default is AuthSub.

• return: true if setting the authorization information in the cookie was successful, false otherwise.
• access: public

Authorizes a Google email address through the Client Login method, described in Google's documentation (http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html). This allows special functions such as posting images and comments.

On a successful authorization, true is returned and the $auth private member is set to the authorization string returned by Google. If the authorization attempt fails, false is returned, and the $error private member is set to the error code returned by Google. Possible error codes can be found at the URL listed above.

• return: The authorization token returned by Google.
• link: http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html
• throws: Picasa_Exception A more generic exception if a different type of error occurs.
• throws: Picasa_Exception_CaptchaRequiredException If the response from Google indicates that a CAPTCHA challenge is required.
• throws: Picasa_Exception_InvalidUsernameOrPasswordException If either the username or password that was supplied was invalid.
• access: public

• string $emailAddress: The email address of the account that is going to be authorized. Can also just be the user's Google username.
• string $password: The account's password, required for authorization.
• string $source: The source, which is a three part string. This string should take the form: "companyName-applicationName-versionID". Optional, the default is null.
• string $loginToken: The token returned by Google when the CAPTCHA challenge was requested. Use Picasa_Exception_CaptchaRequiredException::getCaptchaToken() to get this value. If the client is not responding to a Captcha challenge, leave this null. Optional, the default is null.
• string $loginCaptcha: The text input by the user representing the CAPTCHA challenge presented to them. If the client is not responding to a Captcha challenge, leave this null. Optional, the default is null.
• boolean $saveAuthorizationToCookie: If this is true, the authorization token returned from Google is stored in the users' browser cookie so that it can be retrieved later and the user can be logged in without have to enter his email address and password (assuming the cookie and token both do not expire. false will only store the token in the current instance, which is not persistent and disapears as soon as the page loads. Optional, the default is true.
• int $expires: The number of seconds after the cookie is set that it should expire. If $saveAuthorizationToCookie is false, this parameter is ignored. Optional, the default is 2,592,000 seconds (30 days).
• string $service: The service that the account is being authorized for. Each service has a different service code. The code for Picasa is lh2, which is the default.

Builds a context array from the authorization information in the current instantiation.

This context array is used in several places, including the constructors for Picasa_Image and Picasa_Album. The context array is built in such a way that it can be passed to PHP {@see stream_context_create()} to be used in GET requests.

• return: A context array that can be stored in Picasa::$contextArray and passed to the constructors for other classes in the API such as Picasa_Image and Picasa_Album.
• see: Picasa::contextArray
• link: http://www.php.net/stream_context_create
• access: protected

• boolean $doAuth: true if the authorization information should be included in the array, false otherwise. Sometimes it may be desireable to do an unauthorized request for information from Picasa even when the client has established authorization. Optional, the default is false.
• string $method: The request type that will be used. This context array in practice is typically only used directly for the method {@see file_get_contents()}, which is a get request, so it is probably always correct to pass "GET" here, which is the default value.
• int $contentLength: The size of the data in the request. For "GET" requests, this can be 0, which is the default.
• string $contentType: The type of content being sent in the request. Optional, the default is application/x-www-form-urlencoded.

Copies the album attributes along with all images in the album to a new username.

This requires that the current object be authorized to post images to the destination username's account. Tags are copied along with each image, however comments are not. It's the caller's responsibility to make sure the album passed in is what they want copied; keep in mind that some Picasa functions that fetch albums do not always return all the fields of an image so the parts that are left out are fetched when their getter is called. For instance an album returned by Picasa.getAlbumsByUsername() will not contain the images in it until getImages() is called on it.

• return: Picasa_Album} The new album.
• throws: Picasa_Exception If the user is not authorized to create albums or upload images to the destination account.
• access: public

• string $destinationUsername: The username of the account that the album will be copied to.
• {@link $album: Picasa_Album) The album to copy. This is the album object and not just the album id.

If the current instantiation is authorized using the "AuthSub" method, this actively invalidates the token.

• return: true if the authorization was successfully deactivated. false if it was not.
• throws: Picasa_Exception If the current instantiation is not authorized with AuthSub.
• access: public

Deletes a comment applied to a specific image in Picasa Web Albums.

• return: true if the comment was successfully deleted.
• throws: Picasa_Exception If something was wrong with the post to Picasa. A specific subclass of Picasa_Exception will be thrown based on what kind of problem was encountered, unless the type of error was unknown, in which case Picasa_Exception itself will be thrown. In the case of an exception, the album is not deleted.
• access: public

• string $username: The username on the account that the comment is in.
• string $albumid: The id number of the album that the comment to delete is in.
• string $imageid: The id number of the image that the comment is on.
• string $tag: The id number of the comment to delete.
• $commentid

Deletes a tag applied to a specific image.

Beware that Picasa does not throw an error if the client attempts to delete a tag that does not exist, so the client will have to do error checking on its own. If an album or image that does not exist is supplied, an error will be thrown.

• return: true if the tag was successfully deleted.
• throws: Picasa_Exception If something was wrong with the post to Picasa. This includes if an invalid album or image was specified, but not if an invalid tag name was specified.
• access: public

• string $username: The username on the account that the tag is in.
• string $albumid: The id number of the album that the tag to delete is in.
• string $imageid: The id number of the image that the tag is on.
• string $tag: The title of the tag to delete.

Retrieves an Album as an Entry as opposed to a Feed.

Picasa's data api makes a distinction between the two. The two different types will sometimes contain different fields. This method should only be used if you are sure that the field you need is not accessible through a feed, only through an entry. It is declared protected so that client code cannot call it directly, only extensions of the Picasa class.

• link: http://code.google.com/apis/picasaweb/reference.html#Parameters
• throws: Picasa_Exception If the request was somehow invalid. This could mean that the requested object does not have permission to retrieve the feed or the parameters supplied are not allowed by Picasa, or a number of other possible errors. A subclass of Picasa_Exception will be thrown, which will indicate specifically what the problem was with the request.
• access: protected

• string $username: The username on the account that the album is in.
• string $albumid: The id number of the desired album.

Constructs the line that is necessary for passing authorization information within the HTTP header to Picasa.

The object must already be authenticated when this method is called. Will work with either AuthSub or Client Login authorizations. Note that the line has "\r\n" already appended at the end because it is required for HTTP headers.

• return: The header.
• access: public

Fetches the type of authorization this instantiation is configured with.

• return: Possible return values are Picasa::$AUTH_TYPE_AUTH_SUB, Picasa:$AUTH_TYPE_CLIENT_LOGIN, and null if this object is not authenticated.
• access: public

Gets all comments that meet the criteria specified in the parameters.

The client can request images specific to just a user or to a user and an album. To get comments specific to an image, use getImageById() and call Picasa_Image::getComments() on the returned object. Passing null for any of the parameters will leave it up to Picasa to define the default values.

• return: An array of Picasa_Comment objects, one for each comment in the requested feed.
• throws: Picasa_Exception If something was wrong with the requested feed. A specific subclass of Picasa_Exception will be thrown based on what kind of problem was encountered, unless the type of error was unknown, in which case Picasa_Exception itself will be thrown.
• access: public

• string $username: The username on the account to get the comments out of. It is not possible to get comments without specifying the username, so this field is required.
• string $albumid: The id number of the album that the desired comments are in. Optional, the default is null.
• int $maxResults: The maximum number of results to return. Optional, the default is null.
• int $startIndex: The first element number with the search results to return. Useful for pagination. Optional, the default is null.
• string $visibility: Restrict the search to comments in images with the access rights specified here. Options are "public", "private", and "all". Authorization is required for "private" and "all" options. Optional, default is "public".

Turns a context array into a resource, which can then be used in PHP methods such as http://www.php.net/file_get_contents and http://www.php.net/fopen.

• return: A resource representing the context stored in the $contextArray private member.
• link: http://www.php.net/stream_context_create
• access: public

Retrieves the image with the given id.

• return: The requested image.
• todo: Refactor to use buildQueryParams()
• throws: Picasa_Exception If the request was somehow invalid. For instance, if the image or album do not exist.
• access: public

• string $username: The username on the account that the image is in.
• string $albumid: The id number of the album that the image is located in.
• string $imageid: The id number of the desired image.
• int $thumbsize: Comma-delimited list of thumbnail sizes to fetch. Options are 32, 48, 64, 72, 144, 160, 200, 288, 320, 400, 512, 576, 640, 720, 800. URLs for the corresponding thumbnails are stored in the $thumbUrlMap of the Picasa_Image class. Optional, default is null. The default value will let Picasa choose the thumbnail sizes, which are stored in the $smallThumb, $mediumThumb, and $largeThumb fields of the Picasa_Image class.
• int $imgmax: Size of image to return in the $content field of the Picasa_Image field. Options are 32, 48, 64, 72, 144, 160, 200, 288, 320, 400, 512, 576, 640, 720, 800, 912, 1024, 1152, 1280, 1440, 1600. Only values of 800 and less are displayable within a <a> HTML tag, all other values can only be downloaded directly through the user's browser. Optional, default value is null. The default value will let Picasa determine the size to return, which will not be useable within a <a> tag.

Retrieves all images meeting the supplied parameters.

Passing null for any of the parameters will leave it up to Picasa to define the default values.

• return: An object holding meta information about the requested feed, as well as an array of Picasa_Image objects with each object that meets the supplied parameters.
• link: http://code.google.com/apis/picasaweb/reference.html#Parameters
• throws: Picasa_Exception If the request was somehow invalid. This could mean that the requested object does not have permission to retrieve the feed or the parameters supplied are not allowed by Picasa, or a number of other possible errors. A subclass of Picasa_Exception will be thrown, which will indicate specifically what the problem was with the request.
• access: public

• string $username: The username on the account to get the images for. Optional, default is null.
• int $maxResults: The maximum number of results to return. Optional, the default is null.
• int $startIndex: The first element number with the search results to return. Useful for pagination. Optional, the default is null.
• string $keywords: Space-delimited list of keywords to search for. Title and description are included in the search. Optional, default is an empty string.
• string $tags: Space-delimited list of tags to search for. Only images with all tags in the list are included in the search results. Optional, default is empty string.
• string $visibility: Restrict the search to images with the access rights specified here. Options are "public", "private", and "all". Authorization is required for "private" and "all" options. Optional, default is "public".
• int $thumbsize: Comma-delimited list of thumbnail sizes to fetch. Options are 32, 48, 64, 72, 144, 160, 200, 288, 320, 400, 512, 576, 640, 720, 800. URLs for the corresponding thumbnails are stored in the $thumbUrlMap of the Picasa_Image class. Optional, default is null. The default value will let Picasa choose the thumbnail sizes, which are stored in the $smallThumb, $mediumThumb, and $largeThumb fields of the Picasa_Image class.
• int $imgmax: Size of image to return in the $content field of the Picasa_Image field. Options are 32, 48, 64, 72, 144, 160, 200, 288, 320, 400, 512, 576, 640, 720, 800, 912, 1024, 1152, 1280, 1440, 1600. Only values of 800 and less are displayable within a <a> HTML tag, all other values can only be downloaded directly through the user's browser. Optional, default value is null. The default value will let Picasa determine the size to return, which will not be useable within a <a> tag.
• string $sortDescending: Whether or not to sort the items returned by date added descending.
• string $boundingBox: Searches for images tagged as having been taken within a set of four coordinates. The coordinates should be in the order west, south, east, north
• string $location: Searches for photos tagged as having been taken at a named location. For instance "London".

Determines whether the instantiated Picasa object has been authenticated.

In the case of a AuthSub authentication, the validity of the authentication is actually tested. In the case of ClientLogin authentication, it just checks for the existence of the auth token; there is no way in Picasa's API to test the validity of a ClientLogin authentication. If the instantiation has not been authenticated, this method will look for an auth token in the user's cookie and attempt to authenticate the object automatically, in which case true will be returned.

• return: true if this instantiation is authenticated, false otherwise.
• access: public

Post a new album to Picasa Web Albums.

• return: The album that was posted to Picasa.
• throws: Picasa_Exception If something was wrong with the post to Picasa. A specific subclass of Picasa_Exception will be thrown based on what kind of problem was encountered, unless the type of error was unknown, in which case Picasa_Exception itself will be thrown.
• access: public

• string $username: The username on the account to post the album to.
• string $title: The title to assign to this album.
• string $summary: A summary of the contents of the album. Optional, the default is an empty string.
• string $rights: The access rights to assign to the album. Options are "public" and "private". Optional, the default is "public".
• string $commentingEnabled: Identifies whether or not other users should be allowed to post comments to images in the new album. Optional, the default is "true".
• string $location: The location that the images in the album were taken. Optional, the default is an empty string.
• string $timestamp: The number of miliseconds after the Unix epoch (January 1, 1970) that the photos in the album were taken. Notice that the PHP time() functions returns the number of seconds since the epoch, so that number has to be multiplied by 1000 to be used for this parameter. Optional, the default is null. If null is passed here, the timestamp will be set to the current time.
• string $icon: The image that appears as the album cover. Optional, the default is null.
• string $gmlPosition: The location in the world that this image was taken. The format is latitude and longitude, separated by a space. Optional, the default is null.

Posts an image to a Picasa Web Album.

• return: The newly uploaded image.
• link: http://code.google.com/support/bin/answer.py?answer=63316&topic=10973
• throws: Picasa_Exception If something was wrong with the post to Picasa. A specific subclass of Picasa_Exception will be thrown based on what kind of problem was encountered, unless the type of error was unknown, in which case Picasa_Exception itself will be thrown.
• access: public

• string $username: The username on the account to post the image to.
• string $albumid: The id number of the album to post the image to.
• string $locationOnDisk: The path to the image on the local file system or network. Although this parameter has "OnDisk" in the name, you can specify a URL.
• string $type: The type of image that is being uploaded. Picasa currently accepts "image/bmp", "image/gif", "image/jpeg", and "image/png".
• string $title: The title that the image will be given.
• string $summary: A summary of what is in the image. Optional, the default is an empty string.
• string $keywords: A comma-delimited list of keywords associated with the image. Optional, the default is empty string.
• string $commentingEnabled: Set to true if other users should be able to comment on the image and false if they shouldn't. Optional, the default is true.
• string $timestamp: The number of miliseconds after the Unix epoch (January 1st, 1970) that the image was taken (roughly). Optional, the default is null, which will set $timestamp to the current time.
• string $gmlPosition: The location in the world that this image was taken. The format is latitude and longitude, separated by a space. Optional, the default is null.

Saves the authentication token that was returned from Google to the user's browser in a cookie.

This way it can be accessed later and if it's still valid, the user does not need to be required to log in again. Since this deals with cookies, no output can go to the browser before this method is called or it will fail.

• return: The result of the call to PHP's {@see setcookie()} function.
• link: http://us2.php.net/manual/en/function.setcookie.php
• access: protected

• int $expires: The number of seconds after the current time that the cookie should remain in the user's browser for. Optional, default is2592000 (30 days).

Update the meta data associated with the specified album.

The fields identified by each parameter can be modified, however which photos appear in an album are not. Any parameters left null will remain their current value.

• return: The album that was updated.
• throws: Picasa_Exception If something was wrong with the post to Picasa. A specific subclass of Picasa_Exception will be thrown based on what kind of problem was encountered, unless the type of error was unknown, in which case Picasa_Exception itself will be thrown.
• access: public

• string $username: The username on the account that the album is in.
• string $albumid: The id number of the album to update.
• string $title: The title to assign to this album. Optional, the default is null.
• string $summary: A summary of the contents of the album. Optional, the default is an empty string. Optional, the default is null.
• string $icon: The image that appears as the album cover. Optional, the default is null.
• string $rights: The access rights to assign to the album. Options are "public" and "private". Optional, the default is "public". Optional, the default is null.
• string $commentingEnabled: Identifies whether or not other users should be allowed to post comments to images in the new album. Optional, the default is "true". Optional, the default is null.
• string $location: The location that the images in the album were taken. Optional, the default is an empty string.
• string $timestamp: The number of miliseconds after the Unix epoch (January 1, 1970) that the photos in the album were taken. Notice that the PHP time() functions returns the number of seconds since the epoch, so that number has to be multiplied by 1000 to be used for this parameter. Optional, the default is null.
• string $gmlPosition: The location in the world that this image was taken. The format is latitude and longitude, separated by a space. Optional, the default is null.

Constructs a textual representation of everything in the current instantiation of the object.

• access: public