API Guide Home (Online version only) |

# palmOnePhoto.h File Reference

## Detailed Description

Palm Photos API: This API is used to access Palm Photos database and manipulate images.

Version:
  3.0

The database API provides users with the ability to:

- Get the list of albums.
- Create, delete and rename albums.
- Get the list of photos in each album.
- Add photos to albums.

The image manipulation API provides users with the ability to:

- Create and capture images and video clips.
- Read and write image data.
- Convert images to different formats.
- Display images.
- Scale, rotate and crop images.

Update to be compliant with DCF

- The notion of Unfiled folder has been removed
- In PalmPhotoDeleteAlbum() setting the parameter moveToUnfiled moves the photos in the deleted album to DCIM/Palm instead of the Unfiled folder which was DCIM.

Definition in file palmOnePhoto.h.

Include dependency graph for palmOnePhoto.h:

Go to the source code of this file.

## Data Structures

- struct _PalmPhotoSelectionParam
    Photo selection dialog parameters. More...
- struct _PalmPhotoReadWriteParam
    Photo image manipulation param. More...
- struct _PalmPhotoDisplayParam
    Photo image display parameters. More...
- struct _PalmPhotoCreateParam
    Photo image create parameters. More...
- struct _PalmPhotoCaptureParamV2
    Photo/video image capture parameters. More...

## Typedefs

- typedef Err(*) PalmPhotoReadWriteCallback (void *bufferP, UInt32 *sizeP, void *userDataP)
- typedef Boolean(*) PalmPhotoFilterCallback (PalmPhotoHandle imageH, void *userDataP)
- typedef Boolean(*) PalmPhotoDisplayCallback (void *userDataP)
- typedef Boolean(*) PalmPhotoCaptureCallbackV2 (void *userDataP)
- typedef _PalmPhotoSelectionParam PalmPhotoSelectionParam
    Photo selection dialog parameters.
- typedef _PalmPhotoReadWriteParam PalmPhotoReadWriteParam
    Photo image manipulation param.
- typedef _PalmPhotoDisplayParam PalmPhotoDisplayParam
    Photo image display parameters.
- typedef _PalmPhotoCreateParam PalmPhotoCreateParam
    Photo image create parameters.
- typedef _PalmPhotoCaptureParamV2 PalmPhotoCaptureParamV2
    Photo/video image capture parameters.

## Functions

- Err PalmPhotoLibOpen (UInt16 refNum)
- Err PalmPhotoLibClose (UInt16 refNum)
- Err PalmPhotoLibSleep (UInt16 refNum)
- Err PalmPhotoLibWake (UInt16 refNum)
- UInt16 PalmPhotoAlbumCount (UInt16 refNum)
- UInt16 PalmPhotoGetAlbumID (UInt16 refNum, UInt16 index)
- Err PalmPhotoGetAlbumName (UInt16 refNum, UInt16 albumID, Char *nameP, UInt16 bufSize)
- UInt16 PalmPhotoNewAlbum (UInt16 refNum, const Char *nameP, Err *errP)
- Err PalmPhotoDeleteAlbum (UInt16 refNum, UInt16 albumID, Boolean moveToUnfiled)
- Err PalmPhotoRenameAlbum (UInt16 refNum, UInt16 albumID, const Char *nameP)
- UInt16 PalmPhotoImageCount (UInt16 refNum, UInt16 albumID)
- Err PalmPhotoSelectImages (UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP)
- Err PalmPhotoSelectDlg (UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP, PalmPhotoDlgType dlgType, Boolean handleCard)
- void PalmPhotoFreeSelections (UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP)
- PalmPhotoHandle PalmPhotoCreateImage (UInt16 refNum, const PalmPhotoCreateParam *createParamP, Err *errP)
- PalmPhotoHandle PalmPhotoOpenImage (UInt16 refNum, const PalmPhotoFileLocation *photoFileP, Err *errP)
- void PalmPhotoCloseImage (UInt16 refNum, PalmPhotoHandle imageH)
- Err PalmPhotoGetImageInfo (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoImageInfo *infoP)
- UInt32 PalmPhotoGetImageExtraInfoSize (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoExtraInfoType infoType)
- Err PalmPhotoGetImageExtraInfo (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoExtraInfoParam *extraInfoP)
- Err PalmPhotoSetImageExtraInfo (UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoExtraInfoParam *extraInfoP)
- Err PalmPhotoAddImage (UInt16 refNum, UInt16 albumID, PalmPhotoHandle imageH, PalmPhotoHandle *addedImageH, PalmPhotoQualityType imageQuality)
- Err PalmPhotoDeleteImage (UInt16 refNum, PalmPhotoHandle imageH)
- Err PalmPhotoReadImage (UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoReadWriteParam *readParamP)
- Err PalmPhotoWriteImage (UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoReadWriteParam *writeParamP)
- Err PalmPhotoDisplayImage (UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoDisplayParam *displayParamP)
- Err PalmPhotoGetThumbSize (UInt16 refNum, PalmPhotoHandle imageH, UInt16 *widthP, UInt16 *heightP)
- Err PalmPhotoLibGetVersion (UInt16 refNum, UInt32 sdkVersion, UInt32 *libVersionP)
- Err PalmPhotoScaleImageV2 (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *scaledImageHP, UInt32 width, UInt32 height)
- Err PalmPhotoRotateImageV2 (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *rotatedImageHP, Int16 rotation)
- Err PalmPhotoCropImageV2 (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *croppedImageHP, RectangleType *cropRectP)
- Err PalmPhotoConvertImageV2 (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *convertedImageHP, const PalmPhotoCreateParam *createParamP)
- Err PalmPhotoGetLastErrV2 (UInt16 refNum)
- UInt16 PalmPhotoAlbumCountV2 (UInt16 refNum, UInt16 volumeRef)
- UInt16 PalmPhotoGetAlbumIDV2 (UInt16 refNum, UInt16 volumeRef, UInt16 index)
- UInt16 PalmPhotoNewAlbumV2 (UInt16 refNum, UInt16 volumeRef, const Char *nameP)
- Err PalmPhotoFreeSelectionsV2 (UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP)
- PalmPhotoHandle PalmPhotoCreateImageV2 (UInt16 refNum, const PalmPhotoCreateParam *createParamP)
- PalmPhotoHandle PalmPhotoCaptureImageV2 (UInt16 refNum, const PalmPhotoCaptureParamV2 *captureParamP)
- PalmPhotoHandle PalmPhotoOpenImageV2 (UInt16 refNum, const PalmPhotoFileLocation *photoFileP)
- Err PalmPhotoCloseImageV2 (UInt16 refNum, PalmPhotoHandle imageH)
- Err PalmPhotoAddImageV2 (UInt16 refNum, UInt16 albumID, PalmPhotoHandle imageH, PalmPhotoHandle *addedImageH)
- Boolean PalmPhotoIsCameraAvailableV3 (UInt16 refNum)
- PalmPhotoCaptureResolution PalmPhotoGetSupportedCaptureResolutionsV3 (UInt16 refNum, PalmPhotoMediaType mediaType)
- Err PalmPhotoSelectDlgV3 (UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP, const PalmPhotoCaptureParamV2 *captureParamP, PalmPhotoDlgType dlgType, PalmPhotoMediaType mediaType, Boolean handleCard)
- Err PalmPhotoDisplayImageToSizeV3 (UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoDisplayParam *displayParamP)
- Err PalmPhotoDisplayThumbnailV3 (UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoDisplayParam *displayParamP)

## Typedef Documentation

typedef Boolean(*) PalmPhotoCaptureCallbackV2(void *userDataP)

Capture callback. This function is called during capture image if provided as a parameter. If the function returns false, the capture process will be canceled. New in v2.0.

Parameters:

  | userDataP,: | IN: Pointer to user data set in PalmPhotoCaptureParamV2.

Return values:

  | Boolean | True if the capture process should continue, false otherwise.

Definition at line 113 of file palmOnePhoto.h.

typedef struct _PalmPhotoCaptureParamV2 PalmPhotoCaptureParamV2

Photo/video image capture parameters.

The callback function allows the calling application to cancel the image capture operation. The user may cancel the operation by interacting with the capture application. New in v2.0.

typedef struct _PalmPhotoCreateParam PalmPhotoCreateParam

Photo image create parameters.

Set imageInfo can determines the type of the file. To create a JPEG image, set imageInfo.fileFormat to palmPhotoJPEGFileFormat.

typedef Boolean(*) PalmPhotoDisplayCallback(void *userDataP)

Display callback. This function is called during display image if provided as a parameter. If the function returns false, the display process will be canceled.

Parameters:

  | userDataP,: | IN: Pointer to user data set in PalmPhotoDisplayParam.

Return values:

  | Boolean | True if the display process should continue, false otherwise.

Definition at line 99 of file palmOnePhoto.h.

typedef struct _PalmPhotoDisplayParam PalmPhotoDisplayParam

Photo image display parameters.

The bounds might be ignored by the application. New in v2.0: If playing a video, winH and rect are ignored.

typedef Boolean(*) PalmPhotoFilterCallback(PalmPhotoHandle imageH, void *userDataP)

Selection filter callback. This function is called during a selection if provided as a parameter. Given an image handle, the filter decides whether or not and image should be selected. For example, a user might want to select only JPEG images.

Parameters:

  | imageH,: | IN: Handle of the image to filter.
  | userDataP,: | IN: Pointer to user data set in PalmPhotoSelectionParam.

Return values:

  | Boolean | True if ok to select image, false otherwise.

Definition at line 85 of file palmOnePhoto.h.

typedef Err(*) PalmPhotoReadWriteCallback(void *bufferP, UInt32 *sizeP, void *userDataP)

File streaming callback. During read operations, *sizeP contains the size of the buffer passed to the callback. Setting sizeP before returning in this case is simply ingored. If the user doesn't read all the data in the buffer, the data left will be lost. During write operations, *sizeP contains the max size of the buffer used for writing. sizeP is set to the amount of data to write before the callback returns. Setting sizeP to 0 means no more data to write and the write process should stop. The read/write calllback can be stopped at any time by the callback returning the error code palmPhotoLibErrAbortReadWrite.

Parameters:

  | bufferP,: | IN: Pointer to the buffer containing image data.
  | sizeP,: | IN: Size of the buffer.
  | userDataP,: | IN: Pointer to user data set in PalmPhotoReadWriteParam.

Return values:

  | Err | Error code.

Definition at line 68 of file palmOnePhoto.h.

typedef struct _PalmPhotoReadWriteParam PalmPhotoReadWriteParam

Photo image manipulation param.

This parameter is used to set the callback for reading and writing data of an image. The imageFormat provides the user a way to convert images. For example, reading a JPEG image and setting imageFormat to RGB565 should convert the JPEG to RGB565.

typedef struct _PalmPhotoSelectionParam PalmPhotoSelectionParam

Photo selection dialog parameters.

This structure is used for the selection dialog and direct image selection. When using the PMPSelectImages API, selectionCount contains the maximum number of images that can be selected. If selectionCount is set to PALM_PHOTO_SELECT_ALL, the range would be [offset, end]. If albumID is set to PALM_PHOTO_ALBUM_ALL, all images can be selected.

NOTE: The API allocates memory inside of selectedImages. It is the caller's responsibility to free that memory via PalmPhotoFreeSelections().

## Function Documentation

Err PalmPhotoAddImage | ( | UInt16 | refNum,
|  | UInt16 | albumID,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoHandle * | addedImageH,
|  | PalmPhotoQualityType | imageQuality |
| ) |  |  |

Add an image to a Palm Photos album. A new image is created and added to the Photos database, in the specified album. The image will be re-encoded in JPEG format at the specified quality. If album doesn't exist, the image will be added to the album named "Palm". In the previous versions if the album did not exist, the image was added to the "Unfiled" album. Passing albumID of PALM_PHOTO_ALBUM_ALL results in the image being added to the "Palm" album. In the previous versions passing albumID of PALM_PHOTO_ALBUM_ALL resulted in the image being added to the "Unfiled" album. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | albumID,: | IN: Album ID for the image.
  | imageH,: | IN: Image handle.
  | addedImageH,: | OUT: The new image added to the album.
  | imageQuality,: | IN: Image quality.

Return values:

  | Err | Error code.

Err PalmPhotoAddImageV2 | ( | UInt16 | refNum,
|  | UInt16 | albumID,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoHandle * | addedImageH |
| ) |  |  |

Add an image to a Palm Photos album. The image is added to the indicated Photos album. If the album resides on a different volume than imageH, then the image is copied into the new volume. A handle to the image in the designated album is returned in addedImageH. No image conversion takes place. The content of the image in the album is identical to that of the original image. If album doesn't exist, the image will be added to the "Unfiled" album. Passing albumID of PALM_PHOTO_ALBUM_ALL results in the image being added to the "Unfiled" album.

Parameters:

  | refNum,: | IN: Library reference number.
  | albumID,: | IN: Album ID for the image.
  | imageH,: | IN: Image handle.
  | addedImageH,: | OUT: The new image added to the album.

Return values:

  | Err | Error code.

UInt16 PalmPhotoAlbumCount | ( | UInt16 | refNum | ) |

Get the number of albums in Palm Photos. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.

Return values:

  | UInt16 | Album count.

UInt16 PalmPhotoAlbumCountV2 | ( | UInt16 | refNum,
|  | UInt16 | volumeRef |
| ) |  |  |

Get the number of albums in Palm Photos residing on the specified volume. If volumeRef is 0, then the location is on the handheld. Otherwise, it is in VFS.

Parameters:

  | refNum,: | IN: Library reference number.
  | volumeRef,: | IN: Volume to search for photo albums.

Return values:

  | UInt16 | Album count.

PalmPhotoHandle PalmPhotoCaptureImageV2 | ( | UInt16 | refNum,
|  | const PalmPhotoCaptureParamV2 * | captureParamP |
| ) |  |  |

Capture a new still image or video clip using the built-in camera.

New functionality added in 3.0: Can capture video as well as still images. (For video, height and width in captureParam.imageInfo must match a supported resolution as returned by PalmPhotoGetSupportedCaptureResolutionsV3. Location in captureParam.fileLocation must be a VFSFile.) Can limit size (in bytes) of captured media. (Set captureParam.imageInfo.fileSize to the desired limit. If fileSize = 0, no constraint s placed on ithe file size.)

Parameters:

  | refNum,: | IN: Library reference number.
  | captureParamP,: | IN: Palm Photo capture parameter.

Return values:

  | PalmPhotoHandle | The newly created photo handle or NULL if unsuccessful.

void PalmPhotoCloseImage | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH |
| ) |  |  |

Close an image. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.

Err PalmPhotoCloseImageV2 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH |
| ) |  |  |

Close an image.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.

Return values:

  | Err | Error code.

Err PalmPhotoConvertImageV2 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoHandle * | convertedImageHP,
|  | const PalmPhotoCreateParam * | createParamP |
| ) |  |  |

Convert an image. New in v2.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | convertedImageHP,: | OUT: The new image converted.
  | createParamP,: | IN: File information and location for the new image.

Return values:

  | Err | Error code.

PalmPhotoHandle PalmPhotoCreateImage | ( | UInt16 | refNum,
|  | const PalmPhotoCreateParam * | createParamP,
|  | Err * | errP |
| ) |  |  |

Create a new image. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | createParamP,: | IN: Palm Photo create parameter.
  | errP,: | OUT: Error code.

Return values:

  | PalmPhotoHandle | The newly created photo handle or NULL if unsuccessful.

PalmPhotoHandle PalmPhotoCreateImageV2 | ( | UInt16 | refNum,
|  | const PalmPhotoCreateParam * | createParamP |
| ) |  |  |

Create a new image.

Parameters:

  | refNum,: | IN: Library reference number.
  | createParamP,: | IN: Palm Photo create parameter.

Return values:

  | PalmPhotoHandle | The newly created photo handle or NULL if unsuccessful.

Err PalmPhotoCropImageV2 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoHandle * | croppedImageHP,
|  | RectangleType * | cropRectP |
| ) |  |  |

Return a cropped image. New in v2.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | croppedImageHP,: | OUT: The new image cropped.
  | cropRectP,: | IN: Cropping rectangle.

Return values:

  | Err | Error code.

Err PalmPhotoDeleteAlbum | ( | UInt16 | refNum,
|  | UInt16 | albumID,
|  | Boolean | moveToUnfiled |
| ) |  |  |

Delete an album by album ID.

Parameters:

  | refNum,: | IN: Library reference number.
  | albumID,: | IN: ID of the Album to delete.
  | moveToUnfiled,: | IN: If true, photos from the deleted album are moved to /DCIM/Palm folder. Otherwise, they are deleted. In previous versions the Unfiled album was mapped to the /DCIM folder.

Return values:

  | Err | Error code.

Err PalmPhotoDeleteImage | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH |
| ) |  |  |

Delete an image.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.

Return values:

  | Err | Error code.

Err PalmPhotoDisplayImage | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | const PalmPhotoDisplayParam * | displayParamP |
| ) |  |  |

Display an image or play a video. A still image referenced by imageH will be drawn in the window and rectangle specified within *displayParamP. If the window handle is NULL, the current draw window is used. A video referenced by imageH will be played in the video player, and the window and rectangle will be ignored.

The image is displayed "shrink to fit" mode, where 100% of the image is represented on the handheld display. (See also PalmPhotoDisplayImageToSizeV3 for "best fit" scaling.)

If the callback function returns false, the Photo API will halt the draw or play operation.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | displayParamP,: | IN: Display parameter.

Return values:

  | Err | Error code.

Err PalmPhotoDisplayImageToSizeV3 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | const PalmPhotoDisplayParam * | displayParamP |
| ) |  |  |

Display an image or play a video. A still image referenced by imageH will be drawn in the window and rectangle specified within *displayParamP. If the window handle is NULL, the current draw window is used. A video referenced by imageH will be played in the video player, and the window and rectangle will be ignored.

The image is displayed in "best fit" mode, scaled exactly so that the rectangle is completely filled, then cropping anything outside the rectangle. (See also PalmPhotoDisplayImage for shrink-to-fit scaling.)

If the callback function returns false, the Photo API will halt the draw or play operation.

New in v3.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | displayParamP,: | IN: Display parameter.

Return values:

  | Err | Error code.

Err PalmPhotoDisplayThumbnailV3 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | const PalmPhotoDisplayParam * | displayParamP |
| ) |  |  |

Display thumbnail for still image or video.

Thumbnail for the image or video referenced by imageH will be drawn in the window and rectangle specified within *displayParamP. (In the case of video, displays the first frame.) Use PalmPhotoGetThumbSize() first to get the thumbnail size. If the window handle is NULL, the current draw window is used.

If the callback function returns false, the Photo API will halt the draw or play operation.

New in v3.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | displayParamP,: | IN: Display parameter.

Return values:

  | Err | Error code.

void PalmPhotoFreeSelections | ( | UInt16 | refNum,
|  | PalmPhotoSelectionParam * | photoSelectionP |
| ) |  |  |

Free memory allocated during the photos selection. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | photoSelectionP,: | IN,OUT: Palm Photo selection parameter.

Err PalmPhotoFreeSelectionsV2 | ( | UInt16 | refNum,
|  | PalmPhotoSelectionParam * | photoSelectionP |
| ) |  |  |

Free memory allocated during the photos selection.

Parameters:

  | refNum,: | IN: Library reference number.
  | photoSelectionP,: | IN,OUT: Palm Photo selection parameter.

Return values:

  | Err | Error code.

UInt16 PalmPhotoGetAlbumID | ( | UInt16 | refNum,
|  | UInt16 | index |
| ) |  |  |

Get an album ID given the album index. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | index,: | IN: Album index.

Return values:

  | UInt16 | Album ID. If album doesn't exist, return PALM_PHOTO_ALBUM_ALL.

UInt16 PalmPhotoGetAlbumIDV2 | ( | UInt16 | refNum,
|  | UInt16 | volumeRef,
|  | UInt16 | index |
| ) |  |  |

Get an album ID given the album index and volume. If volumeRef is 0, then the location is on the handheld. Otherwise, it is in VFS.

Parameters:

  | refNum,: | IN: Library reference number.
  | volumeRef,: | IN: Volume to search for photo album.
  | index,: | IN: Album index.

Return values:

  | UInt16 | Album ID. If album doesn't exist, return PALM_PHOTO_ALBUM_ALL.

Err PalmPhotoGetAlbumName | ( | UInt16 | refNum,
|  | UInt16 | albumID,
|  | Char * | nameP,
|  | UInt16 | bufSize |
| ) |  |  |

Get an album name given the album ID. The buffer that will hold the album name is allocated by the user.

Parameters:

  | refNum,: | IN: Library reference number.
  | albumID,: | IN: Album ID
  | nameP,: | OUT: Buffer that will contain the name of the album.
  | bufSize,: | IN: Size of the buffer pointed by nameP.

Return values:

  | Err | Error code.

Err PalmPhotoGetImageExtraInfo | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoExtraInfoParam * | extraInfoP |
| ) |  |  |

Get an image extra information.

Note: new info types (palmPhotoExtraInfoSound and palmPhotoExtraInfoUID) added in 3.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | extraInfoP,: | OUT: Structure that will hold the extra info requested.

Return values:

  | Err | Error code.

UInt32 PalmPhotoGetImageExtraInfoSize | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoExtraInfoType | infoType |
| ) |  |  |

Get an image extra information size.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | infoType,: | IN: Extra info type to retrieve the size from.

Return values:

  | UInt32 | The size of the extra information of the specified type.

Err PalmPhotoGetImageInfo | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoImageInfo * | infoP |
| ) |  |  |

Get an image information.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | infoP,: | OUT: Image info structure.

Return values:

  | Err | Error code.

Err PalmPhotoGetLastErrV2 | ( | UInt16 | refNum | ) |

Get the error code from the last Photo API function that executed. Sets the Photo API error code to errNone, if the library is open. If the library is not open, it does not set the error code and returns palmPhotoLibErrNotOpen. New in v2.0.

Parameters:

  | refNum,: | IN: Library reference number.

Return values:

  | Err | Error code.

PalmPhotoCaptureResolution PalmPhotoGetSupportedCaptureResolutionsV3 | ( | UInt16 | refNum,
|  | PalmPhotoMediaType | mediaType |
| ) |  |  |

Returns resolutions that are supported by the still or video camera. Returns zero (palmPhotoCaptureResNone) if no camera, or camera disabled.

Parameters:

  | refNum,: | IN: Library reference number.
  | mediaType,: | IN: palmPhotoMediaTypePhoto or palmPhotoMediaTypeVideo

Return values:

  | PalmPhotoCaptureResolution | Flags (bit is set for each resolution that camera supports).

Err PalmPhotoGetThumbSize | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | UInt16 * | widthP,
|  | UInt16 * | heightP |
| ) |  |  |

Get an image thumbnail size.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | widthP,: | OUT: Width of the thumbnail.
  | heightP,: | OUT: Height of the thumbnail.

Return values:

  | Err | Error code.

UInt16 PalmPhotoImageCount | ( | UInt16 | refNum,
|  | UInt16 | albumID |
| ) |  |  |

Get image count for an album.

Parameters:

  | refNum,: | IN: Library reference number.
  | albumID,: | IN: ID of the Album to retrieve information from.

Return values:

  | Err | Error code.

Boolean PalmPhotoIsCameraAvailableV3 | ( | UInt16 | refNum | ) |

Check for presence of an enabled camera.

Parameters:

  | refNum,: | IN: Library reference number.

Return values:

  | Boolean | false if no camera or camera is disabled.

Err PalmPhotoLibClose | ( | UInt16 | refNum | ) |

Standard library close function

Parameters:

  | refNum,: | IN: library reference number

Return values:

  | Err | Error code.

Err PalmPhotoLibGetVersion | ( | UInt16 | refNum,
|  | UInt32 | sdkVersion,
|  | UInt32 * | libVersionP |
| ) |  |  |

Checks the version of the Palm Photo Library.

Parameters:

  | refNum,: | IN: Library reference number.
  | sdkVersion,: | IN: The version the application expects.
  | libVersionP,: | OUT: The actual version of the library.

Return values:

  | Err | Error code.

Err PalmPhotoLibOpen | ( | UInt16 | refNum | ) |

Standard library open function

Parameters:

  | refNum,: | IN: library reference number

Return values:

  | Err | Error code.

Err PalmPhotoLibSleep | ( | UInt16 | refNum | ) |

Standard library sleep function

Parameters:

  | refNum,: | IN: library reference number

Return values:

  | Err | Error code.

Err PalmPhotoLibWake | ( | UInt16 | refNum | ) |

Standard library wake function

Parameters:

  | refNum,: | IN: library reference number

Return values:

  | Err | Error code.

UInt16 PalmPhotoNewAlbum | ( | UInt16 | refNum,
|  | const Char * | nameP,
|  | Err * | errP |
| ) |  |  |

Create a new album. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | nameP,: | IN: String that contains the name of the new album.
  | errP,: | OUT: Error code.

Return values:

  | UInt16 | If successful, returns the ID of the newly created album. Otherwise, returns PALM_PHOTO_ALBUM_ALL.

UInt16 PalmPhotoNewAlbumV2 | ( | UInt16 | refNum,
|  | UInt16 | volumeRef,
|  | const Char * | nameP |
| ) |  |  |

Create a new album in the selected volume. If volumeRef is 0, then the location is on the handheld. Otherwise, it is in VFS.

Parameters:

  | refNum,: | IN: Library reference number.
  | volumeRef,: | IN: Volume to search for photo album.
  | nameP,: | IN: String that contains the name of the new album.

Return values:

  | UInt16 | If successful, returns the ID of the newly created album. Otherwise, returns PALM_PHOTO_ALBUM_ALL.

PalmPhotoHandle PalmPhotoOpenImage | ( | UInt16 | refNum,
|  | const PalmPhotoFileLocation * | photoFileP,
|  | Err * | errP |
| ) |  |  |

Open an existing image. For compatibility only; new development should use the V2 version.

Parameters:

  | refNum,: | IN: Library reference number.
  | photoFileP,: | IN: Palm Photo file location.
  | errP,: | OUT: Error code.

Return values:

  | PalmPhotoHandle | The opened photo handle or NULL if unsuccessful.

PalmPhotoHandle PalmPhotoOpenImageV2 | ( | UInt16 | refNum,
|  | const PalmPhotoFileLocation * | photoFileP |
| ) |  |  |

Open an existing image.

Parameters:

  | refNum,: | IN: Library reference number.
  | photoFileP,: | IN: Palm Photo file location.

Return values:

  | PalmPhotoHandle | The opened photo handle or NULL if unsuccessful.

Err PalmPhotoReadImage | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | const PalmPhotoReadWriteParam * | readParamP |
| ) |  |  |

Read image data given an image handle. The image format specifies what type of buffer the user expects to copy read data into. For example, to convert a JPEG image to RBG565 data, open a JPEG image, and set readParamP->imageFormat to palmPhotoRGB565FileFormat. The callback function should copy the image data from *bufferP into a buffer referenced within readParamP->userDataP.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | readParamP,: | IN,OUT: Read parameters.

Return values:

  | Err | Error code.

Err PalmPhotoRenameAlbum | ( | UInt16 | refNum,
|  | UInt16 | albumID,
|  | const Char * | nameP |
| ) |  |  |

Rename an album. If Photos has "Camera" album, it also can't be renamed.

Parameters:

  | refNum,: | IN: Library reference number.
  | albumID,: | IN: ID of the Album to delete.
  | nameP,: | IN: New album name.

Return values:

  | Err | Error code.

Err PalmPhotoRotateImageV2 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoHandle * | rotatedImageHP,
|  | Int16 | rotation |
| ) |  |  |

Return a rotated image. New in v2.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | rotatedImageHP,: | OUT: The new image rotated.
  | rotation,: | IN: Rotation angle (rotation is counter-clockwise).

Return values:

  | Err | Error code.

Err PalmPhotoScaleImageV2 | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | PalmPhotoHandle * | scaledImageHP,
|  | UInt32 | width,
|  | UInt32 | height |
| ) |  |  |

Return a scaled image. New in v2.0.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | scaledImageHP,: | OUT: The new image scaled.
  | width,: | IN: New image width (must be <= existing width).
  | height,: | IN: New image height (must be <= existing height).

Return values:

  | Err | Error code.

Err PalmPhotoSelectDlg | ( | UInt16 | refNum,
|  | PalmPhotoSelectionParam * | photoSelectionP,
|  | PalmPhotoDlgType | dlgType,
|  | Boolean | handleCard |
| ) |  |  |

Select images using the Media Selection/Deletion dialog. The selected images are passed in the selection parameter. To free the memory allocated, use the PalmPhotoFreeSelections() function.

Parameters:

  | refNum,: | IN: Library reference number.
  | photoSelectionP,: | IN,OUT: Palm Photo selection parameter. Contains array of selections on return.
  | dlgType,: | IN: Selection dialog type (eg palmPhotoDlgSelection...)
  | handleCard,: | IN: If true, the dialog with intercept card notifications.

Return values:

  | Err | Error code.

Err PalmPhotoSelectDlgV3 | ( | UInt16 | refNum,
|  | PalmPhotoSelectionParam * | photoSelectionP,
|  | const PalmPhotoCaptureParamV2 * | captureParamP,
|  | PalmPhotoDlgType | dlgType,
|  | PalmPhotoMediaType | mediaType,
|  | Boolean | handleCard |
| ) |  |  |

Select images using the Photo Selection/Deletion dialog, with optional camera support. The selected images are passed in the selection parameter. To free the memory allocated, use the PalmPhotoFreeSelections() function.

Parameters:

  | refNum,: | IN:Library reference number.
  | photoSelectionP,: | IN,OUT: Palm Photo selection parameter. Contains array of selections on return.
  | captureParamP,: | IN: Palm Photo capture parameter. Set to null to suppress the camera. Camera only supported for single select dialog type. Camera only supported when media type is photo OR video (not all)
  | dlgType,: | IN: Selection dialog type (eg palmPhotoDlgSelection...)
  | mediaType,: | IN: Dialog displays only photos, only videos, or all media types.
  | handleCard,: | IN: If true, the dialog with intercept card notifications.

Return values:

  | Err | Error code.

Err PalmPhotoSelectImages | ( | UInt16 | refNum,
|  | PalmPhotoSelectionParam * | photoSelectionP |
| ) |  |  |

Select images within a specific range. The selected images are passed in the selection parameter. To free the memory allocated, use the PalmPhotoFreeSelections() function.

Parameters:

  | refNum,: | IN: Library reference number.
  | photoSelectionP,: | IN,OUT: Palm Photo selection parameter. Contains array of selections on return.

Return values:

  | Err | Error code.

Err PalmPhotoSetImageExtraInfo | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | const PalmPhotoExtraInfoParam * | extraInfoP |
| ) |  |  |

Set an image extra information. When user set palmPhotoExtraInfoLocation, if the file name contains illegal characters, the function will remove them. If the file name has an incorrect file extension, the function will add the correct one. For example, if the format is Jpeg, "*22.j" will be converted to "22.jpg".

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN: Image handle.
  | extraInfoP,: | IN: Structure that the extra info the extra info to set.

Return values:

  | Err | Error code.

Err PalmPhotoWriteImage | ( | UInt16 | refNum,
|  | PalmPhotoHandle | imageH,
|  | const PalmPhotoReadWriteParam * | writeParamP |
| ) |  |  |

Write image data given an image handle. The writeParamP->imageFormat parameter specifies the source format the calling application is providing to the API to write into storage. The only valid source formats are RGB565 and RGB888. For example, to convert an RGB565 image to a JPEG, you would create a JPEG image and pass its handle in imageH; then you would set writeParamP->imageFormat to palmPhotoRGB565FileFormat. The actual RGB image data would be referenced by a pointer inside writeParamP->userDataP. The callback function will pass the RGB data to the API by copying it into *bufferP.

Parameters:

  | refNum,: | IN: Library reference number.
  | imageH,: | IN,OUT: Image handle.
  | writeParamP,: | IN: Write parameters.

Return values:

  | Err | Error code.

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:07:53 2008 for Palm API Guide