API Guide Home (Online version only) |

# palmOnePhoto.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup Imaging
    00007  */
    00008
    00009 /**
    00010  * @file    palmOnePhoto.h
    00011  * @version 3.0
    00012  *
    00013  * @brief Palm Photos API: This API is used to access Palm Photos database and manipulate images.
    00014  *
    00015  * The database API provides users with the ability to:
    00016  *  - Get the list of albums.
    00017  *  - Create, delete and rename albums.
    00018  *  - Get the list of photos in each album.
    00019  *  - Add photos to albums.
    00020  *
    00021  * The image manipulation API provides users with the ability to:
    00022  *  - Create and capture images and video clips.
    00023  *  - Read and write image data.
    00024  *  - Convert images to different formats.
    00025  *  - Display images.
    00026  *  - Scale, rotate and crop images.
    00027  *
    00028  * Update to be compliant with DCF
    00029  *  - The notion of Unfiled folder has been removed
    00030  *  - In PalmPhotoDeleteAlbum() setting the parameter moveToUnfiled
    00031  *    moves the photos in the deleted album to DCIM/Palm instead of
    00032  *    the Unfiled folder which was DCIM.
    00033  */
    00034
    00035 #ifndef PALMONE_PHOTO_H_
    00036 #define PALMONE_PHOTO_H_
    00037
    00038 /* Include the common define */
    00039 #include <Common/Libraries/Imaging/palmOnePhotoCommon.h>
    00040
    00041 /* Palm OS common definitions */
    00042 #include <SystemMgr.h>
    00043
    00044
    00045
    00046 /******************************************************************
    00047  * Callback functions
    00048  ******************************************************************/
    00049
    00050 /**
    00051  * File streaming callback.
    00052  * During read operations, *sizeP contains the size of the buffer
    00053  * passed to the callback. Setting sizeP before returning in this
    00054  * case is simply ingored. If the user doesn't read all the data
    00055  * in the buffer, the data left will be lost.
    00056  * During write operations, *sizeP contains the max size of the
    00057  * buffer used for writing. sizeP is set to the amount of data to
    00058  * write before the callback returns. Setting sizeP to 0 means
    00059  * no more data to write and the write process should stop.
    00060  * The read/write calllback can be stopped at any time by the
    00061  * callback returning the error code palmPhotoLibErrAbortReadWrite.
    00062  *
    00063  * @param bufferP:      IN: Pointer to the buffer containing image data.
    00064  * @param sizeP:        IN: Size of the buffer.
    00065  * @param userDataP:    IN: Pointer to user data set in PalmPhotoReadWriteParam.
    00066  * @retval Err Error code.
    00067  */
    00068 typedef Err (*PalmPhotoReadWriteCallback) (
    00069     void    *bufferP,
    00070     UInt32  *sizeP,
    00071     void    *userDataP
    00072 );
    00073
    00074 /**
    00075  * Selection filter callback.
    00076  * This function is called during a selection if provided as a
    00077  * parameter. Given an image handle, the filter decides whether
    00078  * or not and image should be selected. For example, a user might
    00079  * want to select only JPEG images.
    00080  *
    00081  * @param imageH:       IN: Handle of the image to filter.
    00082  * @param userDataP:    IN: Pointer to user data set in PalmPhotoSelectionParam.
    00083  * @retval Boolean True if ok to select image, false otherwise.
    00084  */
    00085 typedef Boolean (*PalmPhotoFilterCallback) (
    00086     PalmPhotoHandle imageH,
    00087     void            *userDataP
    00088 );
    00089
    00090 /**
    00091  * Display callback.
    00092  * This function is called during display image if provided as a
    00093  * parameter. If the function returns false, the display process
    00094  * will be canceled.
    00095  *
    00096  * @param userDataP:    IN: Pointer to user data set in PalmPhotoDisplayParam.
    00097  * @retval Boolean True if the display process should continue, false otherwise.
    00098  */
    00099 typedef Boolean (*PalmPhotoDisplayCallback) (
    00100     void            *userDataP
    00101 );
    00102
    00103 /**
    00104  * Capture callback.
    00105  * This function is called during capture image if provided as a
    00106  * parameter. If the function returns false, the capture process
    00107  * will be canceled.
    00108  * New in v2.0.
    00109  *
    00110  * @param userDataP:    IN: Pointer to user data set in PalmPhotoCaptureParamV2.
    00111  * @retval Boolean True if the capture process should continue, false otherwise.
    00112  */
    00113 typedef Boolean (*PalmPhotoCaptureCallbackV2) (
    00114     void            *userDataP
    00115 );
    00116
    00117
    00118 /******************************************************************
    00119  * Callback function parameters
    00120  ******************************************************************/
    00121
    00122 /**
    00123  * @brief Photo selection dialog parameters.
    00124  *
    00125  * This structure is used for the selection dialog and direct image selection.
    00126  * When using the PMPSelectImages API, selectionCount contains the maximum
    00127  * number of images that can be selected.  If selectionCount is set to
    00128  * PALM_PHOTO_SELECT_ALL, the range would be [offset, end]. If albumID is set
    00129  * to PALM_PHOTO_ALBUM_ALL, all images can be selected.
    00130  *
    00131  * NOTE: The API allocates memory inside of selectedImages. It is the caller's
    00132  * responsibility to free that memory via PalmPhotoFreeSelections().
    00133  */
    00134 typedef struct _PalmPhotoSelectionParam
    00135 {
    00136     UInt16                  albumID;        /**< IN: Album ID for selection.                    */
    00137     UInt16                  reserved;       /**< reserved for future use                        */
    00138     UInt32                  offset;         /**< IN: Range start.                               */
    00139     Int32                   selectionCount; /**< IN: Number of images to select.                */
    00140     PalmPhotoFilterCallback filterCallback; /**< IN: Callback to filter the selections.         */
    00141     void                    *userDataP;     /**< IN: User data to be passed during callback.    */
    00142     PalmPhotoSelections     selectedImages; /**< OUT: Struct containing handle array.           */
    00143 } PalmPhotoSelectionParam;
    00144
    00145
    00146 /**
    00147  * @brief Photo image manipulation param.
    00148  *
    00149  * This parameter is used to set the callback for reading and writing
    00150  * data of an image. The imageFormat provides the user a way to convert
    00151  * images. For example, reading a JPEG image and setting imageFormat to
    00152  * RGB565 should convert the JPEG to RGB565.
    00153  */
    00154 typedef struct _PalmPhotoReadWriteParam
    00155 {
    00156     PalmPhotoFileFormat         imageFormat;    /**< IN: Memory file image format.  */
    00157     UInt16                      reserved;       /**< reserved for future use        */
    00158     PalmPhotoReadWriteCallback  rwCallback;     /**< IN: Read/Write callback.       */
    00159     void                        *userDataP;     /**< IN: User data.                 */
    00160 } PalmPhotoReadWriteParam;
    00161
    00162
    00163 /**
    00164  * @brief Photo image display parameters.
    00165  *
    00166  * The bounds might be ignored by the application.
    00167  * New in v2.0: If playing a video, winH and rect are ignored.
    00168  */
    00169 typedef struct _PalmPhotoDisplayParam
    00170 {
    00171     WinHandle                   winH;               /**< IN: WinHandle.             */
    00172     RectangleType               rect;               /**< IN: Display rectangle.     */
    00173     PalmPhotoDisplayCallback    displayCallback;    /**< IN: display callback.      */
    00174     void                        *userDataP;         /**< IN: User data.             */
    00175 } PalmPhotoDisplayParam;
    00176
    00177 /**
    00178  * @brief Photo image create parameters.
    00179  *
    00180  * Set imageInfo can determines the type of the file.  To create a
    00181  * JPEG image, set imageInfo.fileFormat to palmPhotoJPEGFileFormat.
    00182  */
    00183
    00184 typedef struct _PalmPhotoCreateParam
    00185 {
    00186     PalmPhotoFileLocation   fileLocation;   /**< IN: file location of new file.     */
    00187     PalmPhotoImageInfo      imageInfo;      /**< IN: file information.              */
    00188 } PalmPhotoCreateParam;
    00189
    00190 /**
    00191  * @brief Photo/video image capture parameters.
    00192  *
    00193  * The callback function allows the calling application to cancel the image
    00194  * capture operation.  The user may cancel the operation by interacting with
    00195  * the capture application.
    00196  * New in v2.0.
    00197  */
    00198
    00199 typedef struct _PalmPhotoCaptureParamV2
    00200 {
    00201     PalmPhotoFileLocation       fileLocation;       /**< IN: file location of new file. */
    00202                                                     /**     (Note: only VFSFile         */
    00203                                                     /**     supported for video)        */
    00204     PalmPhotoImageInfo          imageInfo;          /**< IN: file information.          */
    00205     PalmPhotoCaptureCallbackV2  captureCallback;    /**< IN: capture callback.          */
    00206     void                        *userDataP;         /**< IN: User data.                 */
    00207
    00208 } PalmPhotoCaptureParamV2;
    00209
    00210
    00211 /*********************************************************************
    00212  * API Prototypes
    00213  *********************************************************************/
    00214
    00215 #ifdef __cplusplus
    00216 extern "C" {
    00217 #endif
    00218
    00219 /******************************************************************
    00220  * Standard library open, close, sleep and wake functions
    00221  ******************************************************************/
    00222
    00223 /// Standard library open function
    00224 /// @param refNum: IN: library reference number
    00225 /// @retval Err Error code.
    00226 extern Err PalmPhotoLibOpen(UInt16 refNum)
    00227     PMP_LIB_TRAP(sysLibTrapOpen);
    00228
    00229 /// Standard library close function
    00230 /// @param refNum: IN: library reference number
    00231 /// @retval Err Error code.
    00232 extern Err PalmPhotoLibClose(UInt16 refNum)
    00233     PMP_LIB_TRAP(sysLibTrapClose);
    00234
    00235 /// Standard library sleep function
    00236 /// @param refNum: IN: library reference number
    00237 /// @retval Err Error code.
    00238 extern Err PalmPhotoLibSleep(UInt16 refNum)
    00239     PMP_LIB_TRAP(sysLibTrapSleep);
    00240
    00241 /// Standard library wake function
    00242 /// @param refNum: IN: library reference number
    00243 /// @retval Err Error code.
    00244 extern Err PalmPhotoLibWake(UInt16 refNum)
    00245     PMP_LIB_TRAP(sysLibTrapWake);
    00246
    00247
    00248 /******************************************************************
    00249  * Custom library API functions
    00250  ******************************************************************/
    00251
    00252 /******************************************************************
    00253  * Photo API v1.0 functions
    00254  ******************************************************************/
    00255
    00256 /**
    00257  * Get the number of albums in Palm Photos.
    00258  * For compatibility only; new development should use the V2 version.
    00259  *
    00260  * @param refNum:   IN: Library reference number.
    00261  * @retval          UInt16 Album count.
    00262  */
    00263 extern UInt16  PalmPhotoAlbumCount(UInt16 refNum)
    00264     PMP_LIB_TRAP(sysLibTrapBase + 5);
    00265
    00266 /**
    00267  * Get an album ID given the album index.
    00268  * For compatibility only; new development should use the V2 version.
    00269  *
    00270  * @param refNum:   IN: Library reference number.
    00271  * @param index:    IN: Album index.
    00272  * @retval          UInt16 Album ID. If album doesn't exist, return PALM_PHOTO_ALBUM_ALL.
    00273  */
    00274 extern UInt16 PalmPhotoGetAlbumID(UInt16 refNum, UInt16 index)
    00275     PMP_LIB_TRAP(sysLibTrapBase + 6);
    00276
    00277 /**
    00278  * Get an album name given the album ID.
    00279  * The buffer that will hold the album name is allocated by the user.
    00280  *
    00281  * @param refNum:   IN:  Library reference number.
    00282  * @param albumID:  IN:  Album ID
    00283  * @param nameP:    OUT: Buffer that will contain the name of the album.
    00284  * @param bufSize:  IN:  Size of the buffer pointed by nameP.
    00285  * @retval          Err Error code.
    00286  */
    00287 extern Err PalmPhotoGetAlbumName(UInt16 refNum, UInt16 albumID, Char *nameP, UInt16 bufSize)
    00288     PMP_LIB_TRAP(sysLibTrapBase + 7);
    00289
    00290 /**
    00291  * Create a new album.
    00292  * For compatibility only; new development should use the V2 version.
    00293  *
    00294  * @param refNum:   IN:  Library reference number.
    00295  * @param nameP:    IN:  String that contains the name of the new album.
    00296  * @param errP:     OUT: Error code.
    00297  * @retval          UInt16 If successful, returns the ID of the newly created album.
    00298  *                  Otherwise, returns PALM_PHOTO_ALBUM_ALL.
    00299  */
    00300 extern UInt16 PalmPhotoNewAlbum(UInt16 refNum, const Char *nameP, Err *errP)
    00301     PMP_LIB_TRAP(sysLibTrapBase + 8);
    00302
    00303 /**
    00304  * Delete an album by album ID.
    00305  *
    00306  * @param refNum:           IN: Library reference number.
    00307  * @param albumID:          IN: ID of the Album to delete.
    00308  * @param moveToUnfiled:    IN: If true, photos from the deleted album are moved to /DCIM/Palm
    00309  *                              folder. Otherwise, they are deleted. In previous versions
    00310  *                              the Unfiled album was mapped to the /DCIM folder.
    00311  * @retval                  Err Error code.
    00312  */
    00313 extern Err PalmPhotoDeleteAlbum(UInt16 refNum, UInt16 albumID, Boolean moveToUnfiled)
    00314     PMP_LIB_TRAP(sysLibTrapBase + 9);
    00315
    00316 /**
    00317  * Rename an album.
    00318  * If Photos has "Camera" album, it also can't be renamed.
    00319  *
    00320  * @param refNum:   IN: Library reference number.
    00321  * @param albumID:  IN: ID of the Album to delete.
    00322  * @param nameP:    IN: New album name.
    00323  * @retval          Err Error code.
    00324  */
    00325 extern Err PalmPhotoRenameAlbum(UInt16 refNum, UInt16 albumID, const Char *nameP)
    00326     PMP_LIB_TRAP(sysLibTrapBase + 10);
    00327
    00328 /**
    00329  * Get image count for an album.
    00330  *
    00331  * @param refNum:   IN: Library reference number.
    00332  * @param albumID:  IN: ID of the Album to retrieve information from.
    00333  * @retval          Err Error code.
    00334  */
    00335 extern UInt16 PalmPhotoImageCount(UInt16 refNum, UInt16 albumID)
    00336     PMP_LIB_TRAP(sysLibTrapBase + 11);
    00337
    00338 /**
    00339  * Select images within a specific range.
    00340  * The selected images are passed in the selection parameter.
    00341  * To free the memory allocated, use the PalmPhotoFreeSelections() function.
    00342  *
    00343  * @param refNum:           IN: Library reference number.
    00344  * @param photoSelectionP:  IN,OUT: Palm Photo selection parameter. Contains array of selections on return.
    00345  * @retval                  Err Error code.
    00346  */
    00347 extern Err PalmPhotoSelectImages(UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP)
    00348     PMP_LIB_TRAP(sysLibTrapBase + 12);
    00349
    00350 /**
    00351  * Select images using the Media Selection/Deletion dialog.
    00352  * The selected images are passed in the selection parameter.
    00353  * To free the memory allocated, use the PalmPhotoFreeSelections() function.
    00354  *
    00355  * @param refNum:           IN: Library reference number.
    00356  * @param photoSelectionP:  IN,OUT: Palm Photo selection parameter. Contains array of selections on return.
    00357  * @param dlgType:          IN: Selection dialog type (eg palmPhotoDlgSelection...)
    00358  * @param handleCard:       IN: If true, the dialog with intercept card notifications.
    00359  * @retval                  Err Error code.
    00360  */
    00361 extern Err PalmPhotoSelectDlg(UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP, PalmPhotoDlgType dlgType, Boolean handleCard)
    00362     PMP_LIB_TRAP(sysLibTrapBase + 13);
    00363
    00364 /**
    00365  * Free memory allocated during the photos selection.
    00366  * For compatibility only; new development should use the V2 version.
    00367  *
    00368  * @param refNum:           IN: Library reference number.
    00369  * @param photoSelectionP:  IN,OUT: Palm Photo selection parameter.
    00370  */
    00371 extern void PalmPhotoFreeSelections(UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP)
    00372     PMP_LIB_TRAP(sysLibTrapBase + 14);
    00373
    00374 /**
    00375  * Create a new image.
    00376  * For compatibility only; new development should use the V2 version.
    00377  *
    00378  * @param refNum:       IN:  Library reference number.
    00379  * @param createParamP: IN:  Palm Photo create parameter.
    00380  * @param errP:         OUT: Error code.
    00381  * @retval              PalmPhotoHandle The newly created photo handle or NULL if unsuccessful.
    00382  */
    00383 extern PalmPhotoHandle PalmPhotoCreateImage(UInt16 refNum, const PalmPhotoCreateParam *createParamP, Err *errP)
    00384     PMP_LIB_TRAP(sysLibTrapBase + 15);
    00385
    00386 /**
    00387  * Open an existing image.
    00388  * For compatibility only; new development should use the V2 version.
    00389  *
    00390  * @param refNum:       IN:  Library reference number.
    00391  * @param photoFileP:   IN:  Palm Photo file location.
    00392  * @param errP:         OUT: Error code.
    00393  * @retval              PalmPhotoHandle The opened photo handle or NULL if unsuccessful.
    00394  */
    00395 extern PalmPhotoHandle PalmPhotoOpenImage(UInt16 refNum, const PalmPhotoFileLocation *photoFileP, Err *errP)
    00396     PMP_LIB_TRAP(sysLibTrapBase + 16);
    00397
    00398 /**
    00399  * Close an image.
    00400  * For compatibility only; new development should use the V2 version.
    00401  *
    00402  * @param refNum:   IN: Library reference number.
    00403  * @param imageH:   IN: Image handle.
    00404  */
    00405 extern void PalmPhotoCloseImage(UInt16 refNum, PalmPhotoHandle imageH)
    00406     PMP_LIB_TRAP(sysLibTrapBase + 17);
    00407
    00408 /**
    00409  * Get an image information.
    00410  *
    00411  * @param refNum:   IN:  Library reference number.
    00412  * @param imageH:   IN:  Image handle.
    00413  * @param infoP:    OUT: Image info structure.
    00414  * @retval          Err Error code.
    00415  */
    00416 extern Err PalmPhotoGetImageInfo(UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoImageInfo *infoP)
    00417     PMP_LIB_TRAP(sysLibTrapBase + 18);
    00418
    00419 /**
    00420  * Get an image extra information size.
    00421  *
    00422  * @param refNum:   IN: Library reference number.
    00423  * @param imageH:   IN: Image handle.
    00424  * @param infoType: IN: Extra info type to retrieve the size from.
    00425  * @retval          UInt32 The size of the extra information of the specified type.
    00426  */
    00427 extern UInt32 PalmPhotoGetImageExtraInfoSize (UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoExtraInfoType infoType)
    00428     PMP_LIB_TRAP(sysLibTrapBase + 19);
    00429
    00430 /**
    00431  * Get an image extra information.
    00432  *
    00433  * Note: new info types (palmPhotoExtraInfoSound and palmPhotoExtraInfoUID) added in 3.0.
    00434  *
    00435  * @param refNum:       IN:  Library reference number.
    00436  * @param imageH:       IN:  Image handle.
    00437  * @param extraInfoP:   OUT: Structure that will hold the extra info requested.
    00438  * @retval              Err Error code.
    00439  */
    00440 extern Err PalmPhotoGetImageExtraInfo(UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoExtraInfoParam *extraInfoP)
    00441     PMP_LIB_TRAP(sysLibTrapBase + 20);
    00442
    00443 /**
    00444  * Set an image extra information.
    00445  * When user set palmPhotoExtraInfoLocation, if the file name contains illegal
    00446  * characters, the function will remove them. If the file name has an incorrect
    00447  * file extension, the function will add the correct one.
    00448  * For example, if the format is Jpeg, "*22.j" will be converted to "22.jpg".
    00449  *
    00450  * @param refNum:       IN: Library reference number.
    00451  * @param imageH:       IN: Image handle.
    00452  * @param extraInfoP:   IN: Structure that the extra info the extra info to set.
    00453  * @retval              Err Error code.
    00454  */
    00455 extern Err PalmPhotoSetImageExtraInfo(UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoExtraInfoParam *extraInfoP)
    00456     PMP_LIB_TRAP(sysLibTrapBase + 21);
    00457
    00458 /**
    00459  * Add an image to a Palm Photos album.
    00460  * A new image is created and added to the Photos database, in the specified album.
    00461  * The image will be re-encoded in JPEG format at the specified quality.
    00462  * If album doesn't exist, the image will be added to the album named "Palm". In the previous
    00463  * versions if the album did not exist, the image was added to the "Unfiled" album.
    00464  * Passing albumID of PALM_PHOTO_ALBUM_ALL results in the image being added
    00465  * to the "Palm" album. In the previous versions passing albumID of
    00466  * PALM_PHOTO_ALBUM_ALL resulted in the image being added to the "Unfiled" album.
    00467  * For compatibility only; new development should use the V2 version.
    00468  *
    00469  * @param refNum:       IN:  Library reference number.
    00470  * @param albumID:      IN:  Album ID for the image.
    00471  * @param imageH:       IN:  Image handle.
    00472  * @param addedImageH:  OUT: The new image added to the album.
    00473  * @param imageQuality: IN:  Image quality.
    00474  * @retval              Err Error code.
    00475  */
    00476 extern Err PalmPhotoAddImage(UInt16 refNum, UInt16 albumID, PalmPhotoHandle imageH, PalmPhotoHandle* addedImageH, PalmPhotoQualityType imageQuality)
    00477     PMP_LIB_TRAP(sysLibTrapBase + 22);
    00478
    00479 /**
    00480  * Delete an image.
    00481  *
    00482  * @param refNum:       IN: Library reference number.
    00483  * @param imageH:       IN: Image handle.
    00484  * @retval              Err Error code.
    00485  */
    00486 extern Err PalmPhotoDeleteImage(UInt16 refNum, PalmPhotoHandle imageH)
    00487     PMP_LIB_TRAP(sysLibTrapBase + 23);
    00488
    00489 /**
    00490  * Read image data given an image handle.
    00491  * The image format specifies what type of buffer the user expects to copy
    00492  * read data into. For example, to convert a JPEG image to RBG565 data, open
    00493  * a JPEG image, and set readParamP->imageFormat to palmPhotoRGB565FileFormat.
    00494  * The callback function should copy the image data from *bufferP into a buffer
    00495  * referenced within readParamP->userDataP.
    00496  *
    00497  * @param refNum:       IN: Library reference number.
    00498  * @param imageH:       IN: Image handle.
    00499  * @param readParamP:   IN,OUT: Read parameters.
    00500  * @retval              Err Error code.
    00501  */
    00502 extern Err PalmPhotoReadImage(UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoReadWriteParam *readParamP)
    00503     PMP_LIB_TRAP(sysLibTrapBase + 24);
    00504
    00505 /**
    00506  * Write image data given an image handle.
    00507  * The writeParamP->imageFormat parameter specifies the source format the calling
    00508  * application is providing to the API to write into storage.  The only valid source
    00509  * formats are RGB565 and RGB888.  For example, to convert an RGB565 image to a JPEG,
    00510  * you would create a JPEG image and pass its handle in imageH; then you would set
    00511  * writeParamP->imageFormat to palmPhotoRGB565FileFormat.  The actual RGB image data
    00512  * would be referenced by a pointer inside writeParamP->userDataP.  The callback
    00513  * function will pass the RGB data to the API by copying it into *bufferP.
    00514  *
    00515  * @param refNum:       IN: Library reference number.
    00516  * @param imageH:       IN,OUT: Image handle.
    00517  * @param writeParamP:  IN: Write parameters.
    00518  * @retval              Err Error code.
    00519  */
    00520 extern Err PalmPhotoWriteImage(UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoReadWriteParam *writeParamP)
    00521     PMP_LIB_TRAP(sysLibTrapBase + 25);
    00522
    00523 /**
    00524  * Display an image or play a video.
    00525  * A still image referenced by imageH will be drawn in the window and
    00526  * rectangle specified within *displayParamP.  If the window handle is NULL, the
    00527  * current draw window is used.  A video referenced by imageH will be played in
    00528  * the video player, and the window and rectangle will be ignored.
    00529  *
    00530  * The image is displayed "shrink to fit" mode, where 100% of the image
    00531  * is represented on the handheld display. (See also PalmPhotoDisplayImageToSizeV3
    00532  * for "best fit" scaling.)
    00533  *
    00534  * If the callback function returns false, the Photo API will halt
    00535  * the draw or play operation.
    00536  *
    00537  * @param refNum:           IN: Library reference number.
    00538  * @param imageH:           IN: Image handle.
    00539  * @param displayParamP:    IN: Display parameter.
    00540  * @retval                  Err Error code.
    00541  */
    00542 extern Err PalmPhotoDisplayImage(UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoDisplayParam *displayParamP)
    00543     PMP_LIB_TRAP(sysLibTrapBase + 26);
    00544
    00545 /**
    00546  * Get an image thumbnail size.
    00547  *
    00548  * @param refNum:   IN:  Library reference number.
    00549  * @param imageH:   IN:  Image handle.
    00550  * @param widthP:   OUT: Width of the thumbnail.
    00551  * @param heightP:  OUT: Height of the thumbnail.
    00552  * @retval          Err Error code.
    00553  */
    00554 extern Err PalmPhotoGetThumbSize(UInt16 refNum, PalmPhotoHandle imageH, UInt16 *widthP, UInt16 *heightP)
    00555     PMP_LIB_TRAP(sysLibTrapBase + 27);
    00556
    00557 /**
    00558  * Checks the version of the Palm Photo Library.
    00559  *
    00560  * @param refNum:       IN:  Library reference number.
    00561  * @param sdkVersion:   IN:  The version the application expects.
    00562  * @param libVersionP:  OUT: The actual version of the library.
    00563  * @retval              Err Error code.
    00564  */
    00565 extern Err PalmPhotoLibGetVersion(UInt16 refNum, UInt32 sdkVersion, UInt32* libVersionP)
    00566     PMP_LIB_TRAP(sysLibTrapBase + 29);
    00567
    00568
    00569 /******************************************************************
    00570  * Photo API v2.0 functions
    00571  ******************************************************************/
    00572
    00573 /**
    00574  * Return a scaled image.
    00575  * New in v2.0.
    00576  *
    00577  * @param refNum:           IN:  Library reference number.
    00578  * @param imageH:           IN:  Image handle.
    00579  * @param scaledImageHP:    OUT: The new image scaled.
    00580  * @param width:            IN:  New image width (must be <= existing width).
    00581  * @param height:           IN:  New image height (must be <= existing height).
    00582  * @retval                  Err Error code.
    00583  */
    00584 extern Err PalmPhotoScaleImageV2(UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *scaledImageHP, UInt32 width, UInt32 height)
    00585     PMP_LIB_TRAP(sysLibTrapBase + 30);
    00586
    00587 /**
    00588  * Return a rotated image.
    00589  * New in v2.0.
    00590  *
    00591  * @param refNum:           IN:  Library reference number.
    00592  * @param imageH:           IN:  Image handle.
    00593  * @param rotatedImageHP:   OUT: The new image rotated.
    00594  * @param rotation:         IN:  Rotation angle (rotation is counter-clockwise).
    00595  * @retval                  Err Error code.
    00596  */
    00597 extern Err PalmPhotoRotateImageV2(UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *rotatedImageHP, Int16 rotation)
    00598     PMP_LIB_TRAP(sysLibTrapBase + 31);
    00599
    00600 /**
    00601  * Return a cropped image.
    00602  * New in v2.0.
    00603  *
    00604  * @param refNum:           IN:  Library reference number.
    00605  * @param imageH:           IN:  Image handle.
    00606  * @param croppedImageHP:   OUT: The new image cropped.
    00607  * @param cropRectP:        IN:  Cropping rectangle.
    00608  * @retval                  Err  Error code.
    00609  */
    00610 extern Err PalmPhotoCropImageV2(UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *croppedImageHP, RectangleType *cropRectP)
    00611     PMP_LIB_TRAP(sysLibTrapBase + 32);
    00612
    00613 /**
    00614  * Convert an image.
    00615  * New in v2.0.
    00616  *
    00617  * @param refNum:           IN:  Library reference number.
    00618  * @param imageH:           IN:  Image handle.
    00619  * @param convertedImageHP: OUT: The new image converted.
    00620  * @param createParamP:     IN:  File information and location for the new image.
    00621  * @retval                  Err  Error code.
    00622  */
    00623 extern Err PalmPhotoConvertImageV2(UInt16 refNum, PalmPhotoHandle imageH, PalmPhotoHandle *convertedImageHP, const PalmPhotoCreateParam *createParamP)
    00624     PMP_LIB_TRAP(sysLibTrapBase + 33);
    00625
    00626 /**
    00627  * Get the error code from the last Photo API function that executed.
    00628  * Sets the Photo API error code to errNone, if the library is open.
    00629  * If the library is not open, it does not set the error code and
    00630  * returns palmPhotoLibErrNotOpen.
    00631  * New in v2.0.
    00632  *
    00633  * @param refNum:   IN: Library reference number.
    00634  * @retval          Err Error code.
    00635  */
    00636 extern Err  PalmPhotoGetLastErrV2( UInt16 refNum )
    00637     PMP_LIB_TRAP(sysLibTrapBase + 34);
    00638
    00639 /**
    00640  * Get the number of albums in Palm Photos residing on the specified volume.
    00641  * If volumeRef is 0, then the location is on the handheld.
    00642  * Otherwise, it is in VFS.
    00643  *
    00644  * @param refNum:       IN: Library reference number.
    00645  * @param volumeRef:    IN: Volume to search for photo albums.
    00646  * @retval              UInt16 Album count.
    00647  */
    00648 extern UInt16  PalmPhotoAlbumCountV2(UInt16 refNum, UInt16 volumeRef)
    00649     PMP_LIB_TRAP(sysLibTrapBase + 35);
    00650
    00651 /**
    00652  * Get an album ID given the album index and volume.
    00653  * If volumeRef is 0, then the location is on the handheld.
    00654  * Otherwise, it is in VFS.
    00655  *
    00656  * @param refNum:       IN: Library reference number.
    00657  * @param volumeRef:    IN: Volume to search for photo album.
    00658  * @param index:        IN: Album index.
    00659  * @retval              UInt16 Album ID. If album doesn't exist, return PALM_PHOTO_ALBUM_ALL.
    00660  */
    00661 extern UInt16 PalmPhotoGetAlbumIDV2(UInt16 refNum, UInt16 volumeRef, UInt16 index)
    00662     PMP_LIB_TRAP(sysLibTrapBase + 36);
    00663
    00664 /**
    00665  * Create a new album in the selected volume.
    00666  * If volumeRef is 0, then the location is on the handheld.
    00667  * Otherwise, it is in VFS.
    00668  *
    00669  * @param refNum:       IN: Library reference number.
    00670  * @param volumeRef:    IN: Volume to search for photo album.
    00671  * @param nameP:        IN: String that contains the name of the new album.
    00672  * @retval              UInt16 If successful, returns the ID of the newly created album.
    00673  *                             Otherwise, returns PALM_PHOTO_ALBUM_ALL.
    00674  */
    00675 extern UInt16 PalmPhotoNewAlbumV2(UInt16 refNum, UInt16 volumeRef, const Char *nameP)
    00676     PMP_LIB_TRAP(sysLibTrapBase + 37);
    00677
    00678 /**
    00679  * Free memory allocated during the photos selection.
    00680  *
    00681  * @param refNum:           IN: Library reference number.
    00682  * @param photoSelectionP:  IN,OUT: Palm Photo selection parameter.
    00683  * @retval                  Err Error code.
    00684  */
    00685 extern Err PalmPhotoFreeSelectionsV2(UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP)
    00686     PMP_LIB_TRAP(sysLibTrapBase + 38);
    00687
    00688 /**
    00689  * Create a new image.
    00690  *
    00691  * @param refNum:       IN: Library reference number.
    00692  * @param createParamP: IN: Palm Photo create parameter.
    00693  * @retval              PalmPhotoHandle The newly created photo handle or NULL if unsuccessful.
    00694  */
    00695 extern PalmPhotoHandle PalmPhotoCreateImageV2(UInt16 refNum, const PalmPhotoCreateParam *createParamP)
    00696     PMP_LIB_TRAP(sysLibTrapBase + 39);
    00697
    00698 /**
    00699  * Capture a new still image or video clip using the built-in camera.
    00700  *
    00701  * New functionality added in 3.0:
    00702  * Can capture video as well as still images.
    00703  *     (For video, height and width in captureParam.imageInfo
    00704  *     must match a supported resolution as returned by
    00705  *     PalmPhotoGetSupportedCaptureResolutionsV3. Location
    00706  *     in captureParam.fileLocation must be a VFSFile.)
    00707  * Can limit size (in bytes) of captured media.
    00708  *    (Set captureParam.imageInfo.fileSize to the desired
    00709  *    limit. If fileSize = 0, no constraint s placed on
    00710  *    ithe file size.)
    00711  *
    00712  * @param refNum:           IN: Library reference number.
    00713  * @param captureParamP:    IN: Palm Photo capture parameter.
    00714  * @retval                  PalmPhotoHandle The newly created photo handle or NULL if unsuccessful.
    00715  */
    00716 extern PalmPhotoHandle PalmPhotoCaptureImageV2(UInt16 refNum, const PalmPhotoCaptureParamV2 *captureParamP)
    00717     PMP_LIB_TRAP(sysLibTrapBase + 40);
    00718
    00719 /**
    00720  * Open an existing image.
    00721  *
    00722  * @param refNum:       IN: Library reference number.
    00723  * @param photoFileP:   IN: Palm Photo file location.
    00724  * @retval              PalmPhotoHandle The opened photo handle or NULL if unsuccessful.
    00725  */
    00726 extern PalmPhotoHandle PalmPhotoOpenImageV2(UInt16 refNum, const PalmPhotoFileLocation *photoFileP)
    00727     PMP_LIB_TRAP(sysLibTrapBase + 41);
    00728
    00729 /**
    00730  * Close an image.
    00731  *
    00732  * @param refNum:   IN: Library reference number.
    00733  * @param imageH:   IN: Image handle.
    00734  * @retval          Err Error code.
    00735  */
    00736 extern Err PalmPhotoCloseImageV2(UInt16 refNum, PalmPhotoHandle imageH)
    00737     PMP_LIB_TRAP(sysLibTrapBase + 42);
    00738
    00739 /**
    00740  * Add an image to a Palm Photos album.
    00741  * The image is added to the indicated Photos album.  If the album
    00742  * resides on a different volume than imageH, then the image is copied
    00743  * into the new volume.  A handle to the image in the designated album is
    00744  * returned in addedImageH.
    00745  * No image conversion takes place.  The content of the image in the album is
    00746  * identical to that of the original image.
    00747  * If album doesn't exist, the image will be added to the "Unfiled" album.
    00748  * Passing albumID of PALM_PHOTO_ALBUM_ALL results in the image being added
    00749  * to the "Unfiled" album.
    00750  *
    00751  * @param refNum:       IN:  Library reference number.
    00752  * @param albumID:      IN:  Album ID for the image.
    00753  * @param imageH:       IN:  Image handle.
    00754  * @param addedImageH:  OUT: The new image added to the album.
    00755  * @retval              Err Error code.
    00756  */
    00757 extern Err PalmPhotoAddImageV2(UInt16 refNum, UInt16 albumID, PalmPhotoHandle imageH, PalmPhotoHandle* addedImageH)
    00758     PMP_LIB_TRAP(sysLibTrapBase + 43);
    00759
    00760 /******************************************************************
    00761  * Photo API v3 .0 functions
    00762  ******************************************************************/
    00763
    00764 /**
    00765  * Check for presence of an enabled camera.
    00766  *
    00767  * @param refNum:           IN: Library reference number.
    00768  * @retval                  Boolean false if no camera or camera is disabled.
    00769  *
    00770  */
    00771 extern Boolean PalmPhotoIsCameraAvailableV3(UInt16 refNum)
    00772     PMP_LIB_TRAP(sysLibTrapBase + 44);
    00773
    00774 /**
    00775  * Returns resolutions that are supported by the still or video camera.
    00776  * Returns zero (palmPhotoCaptureResNone) if no camera, or camera disabled.
    00777  *
    00778  * @param refNum:           IN: Library reference number.
    00779  * @param mediaType:        IN: palmPhotoMediaTypePhoto or palmPhotoMediaTypeVideo
    00780  * @retval                  PalmPhotoCaptureResolution Flags (bit is set for each resolution that camera supports).
    00781  *
    00782  */
    00783 extern PalmPhotoCaptureResolution PalmPhotoGetSupportedCaptureResolutionsV3(UInt16 refNum, PalmPhotoMediaType mediaType)
    00784     PMP_LIB_TRAP(sysLibTrapBase + 45);
    00785
    00786 /**
    00787  * Select images using the Photo Selection/Deletion dialog, with
    00788  * optional camera support.
    00789  * The selected images are passed in the selection parameter.
    00790  * To free the memory allocated, use the PalmPhotoFreeSelections() function.
    00791  *
    00792  * @param refNum:           IN:Library reference number.
    00793  * @param photoSelectionP:  IN,OUT: Palm Photo selection parameter. Contains array of selections on return.
    00794  * @param captureParamP:    IN: Palm Photo capture parameter. Set to null to suppress the camera.
    00795  *                              Camera only supported for single select dialog type.
    00796  *                              Camera only supported when media type is photo OR video (not all)
    00797  * @param dlgType:          IN: Selection dialog type (eg palmPhotoDlgSelection...)
    00798  * @param mediaType:        IN: Dialog displays only photos, only videos, or all media types.
    00799  * @param handleCard:       IN: If true, the dialog with intercept card notifications.
    00800  * @retval                  Err Error code.
    00801  */
    00802 extern Err PalmPhotoSelectDlgV3(UInt16 refNum, PalmPhotoSelectionParam *photoSelectionP, const PalmPhotoCaptureParamV2 *captureParamP,
    00803             PalmPhotoDlgType dlgType, PalmPhotoMediaType mediaType, Boolean handleCard)
    00804     PMP_LIB_TRAP(sysLibTrapBase + 46);
    00805
    00806
    00807 /**
    00808  * Display an image or play a video.
    00809  * A still image referenced by imageH will be drawn in the window and
    00810  * rectangle specified within *displayParamP.  If the window handle is NULL, the
    00811  * current draw window is used.  A video referenced by imageH will be played in
    00812  * the video player, and the window and rectangle will be ignored.
    00813  *
    00814  * The image is displayed in "best fit" mode, scaled exactly so that the
    00815  * rectangle is completely filled, then cropping anything outside the
    00816  * rectangle. (See also PalmPhotoDisplayImage for shrink-to-fit scaling.)
    00817  *
    00818  * If the callback function returns false, the Photo API will halt
    00819  * the draw or play operation.
    00820  *
    00821  * New in v3.0.
    00822  *
    00823  * @param refNum:           IN: Library reference number.
    00824  * @param imageH:           IN: Image handle.
    00825  * @param displayParamP:    IN: Display parameter.
    00826  * @retval                  Err Error code.
    00827  */
    00828 extern Err PalmPhotoDisplayImageToSizeV3(UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoDisplayParam *displayParamP)
    00829     PMP_LIB_TRAP(sysLibTrapBase + 47);
    00830
    00831 /**
    00832  * Display thumbnail for still image or video.
    00833  *
    00834  * Thumbnail for the image or video referenced by imageH will be drawn
    00835  * in the window and rectangle specified within *displayParamP. (In the
    00836  * case of video, displays the first frame.) Use PalmPhotoGetThumbSize()
    00837  * first to get the thumbnail size. If the window handle is NULL,
    00838  * the current draw window is used.
    00839  *
    00840  * If the callback function returns false, the Photo API will halt
    00841  * the draw or play operation.
    00842  *
    00843  * New in v3.0.
    00844  *
    00845  * @param refNum:           IN: Library reference number.
    00846  * @param imageH:           IN: Image handle.
    00847  * @param displayParamP:    IN: Display parameter.
    00848  * @retval                  Err Error code.
    00849  */
    00850 extern Err PalmPhotoDisplayThumbnailV3(UInt16 refNum, PalmPhotoHandle imageH, const PalmPhotoDisplayParam *displayParamP)
    00851     PMP_LIB_TRAP(sysLibTrapBase + 53);
    00852
    00853
    00854
    00855 #ifdef __cplusplus
    00856 }
    00857 #endif
    00858
    00859 #endif /* PALMONE_PHOTO_H_ */

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