Diff: USBHostPTP.h

Revision:

4:9c6f5867f050

Parent:

1:71c0e9dc153d

Child:

5:728b5d58e135

--- a/USBHostPTP.h	Fri Aug 23 23:34:05 2013 +0000
+++ b/USBHostPTP.h	Wed Aug 28 03:25:53 2013 +0000
@@ -1,7 +1,16 @@
-/* mbed USBHostPTP Library
- * Copyright (c) 2013 Dwayne Dilbeck
- * This software is distributed under the terms of the GNU Lesser General Public License
- */
+/**
+*  @file USBHostPTP.h
+*  @brief USBHostPTP class definition
+*  @author Dwayne Dilbeck
+*  @date 8/23/2013
+* 
+* mbed USBHostPTP Library
+*
+* @par Copyright:
+*  Copyright (c) 2013 Dwayne Dilbeck
+* @par License:
+*  This software is distributed under the terms of the GNU Lesser General Public License
+*/
 
 
 #ifndef USBHOSTPTP_H
@@ -37,7 +46,7 @@
 
    /**
     * Define a set of flags to make calls to execute Operations a simple wrapper.  
-    * This copied from the Circuits At Home Arduino Library to match thier format.
+    * This structure is copied from the 'Circuits At Home' Arduino Library to match thier format.
     */
    struct OperFlags
         {
@@ -79,45 +88,262 @@
      *  @return true if the operation was succesful
      */
     bool CancelRequest(unsigned int TransactionID);
+    
+    /**
+     *  DeviceResetRequest
+     *  The Device Reset Request is used by the host to return the 
+     *   Still Image Capture Device to the Idle state after the Bulk-pipe
+     *   has stalled. The request may also be used to clear any vendor specified suspend conditions.
+     *
+     *  @param none
+     *
+     *  @return true if the operation was succesful
+     */
     bool DeviceResetRequest(void);
-    bool GetDeviceStatus(void);
-    bool GetExtendedEventData(void);
     
     
+    /**
+     *  GetDeviceStatus
+     *  This request is used by the host to retrieve information needed to 
+     *  clear halted endpoints that result from a device initiated data transfer cancellation.
+     *
+     *  @param none
+     *
+     *  @return true if the operation was succesful
+     */
+    bool GetDeviceStatus(void);
+    
+    /**
+     *  GetExtendedEventData
+     *  The data stage transfers to the host extended information regarding
+     *   an asynchronous event or vendor condition.
+     *
+     *  @param none
+     *
+     *  @return true if the operation was succesful
+     */
+    bool GetExtendedEventData(void);
+    
+    ///Provide external access to deviceInfo
     DeviceInfoStruct deviceInfo;
+    ///provide external access to ObjectInfo
     ObjectInfoStruct objectInfo;
-    
+    ///provide external access to storageInfo
+    StorageInfoStruct storageInfo;
+    ///Provide a visible counter of bytes remaining during long transfers
     uint32_t dataLeftToTransfer;
+    ///Provide a visible value of total data to transfer during long transfers
     uint32_t totalDataToTransfer;
     
-    // Simple PTP operation which has no data stage. Any number of uint32_t params can be supplied.
-    uint16_t Operation(uint16_t opcode, uint8_t nparams = 0, uint32_t *params = NULL);
+    /**
+     *  Simple PTP operation caller which has no data stage. Any number of uint32_t params can be supplied.
+     *
+     *  @param opcode The operation to send to the device for execeution
+     *  @param nparams The number of parameters being supplied for the operation
+     *  @param params  A pointer to the paratmers array to be used.
+     *
+     *  @return A PTP response code
+     */
+     uint16_t Operation(uint16_t opcode, uint8_t nparams = 0, uint32_t *params = NULL);
+     
+     /**
+     * Open a new session on the PTP device, this is required before any other operations besides GetDeviceInfo can be called.
+     *
+     * @param none
+     * @return  A PTP response code
+     */
     uint16_t OpenSession();
-    uint16_t CloseSession();
+    
+    /**
+     * Close the currently open session. The PIMA standard does not allow muliptl session to be open at a time.
+     *
+     * @param none
+     * @return  A PTP response code
+     */
+     uint16_t CloseSession();
+     
+    /**
+     * This command get the device configuration information, including the operations, porperties, and events the divce supports.
+     * @param none
+     * @return  A PTP response code
+     */
     uint16_t GetDeviceInfo();
-
+    
+    /**
+     * Request a device power down.
+     *
+     * @param none
+     * @return  A PTP response code
+     */
     uint16_t PowerDown();
+    
+    /**
+     * Execute a self test
+     *
+     * @param type (Optional) Specify the test to execute.
+     * @param none
+     * @return  A PTP response code
+     */
     uint16_t SelfTest(uint16_t type = 0);
+    
+    /**
+     * Get the number of objects stored on the device
+     *
+     * @param retval a pointer to a uint32_t value , this will be set by the function to return the value
+     * @param storage_id Provide a way to filter by storage ID.
+     * @param format Provide a way to filter by format. PTP devices are not required to support filtering by format
+     * @param assoc  Provide a way to filter by association. PTP devices are not required to support filtering by association
+     * @return  A PTP response code
+     */
     uint16_t GetNumObjects(uint32_t *retval, uint32_t storage_id=0xffffffff, uint16_t format=0x0000, uint32_t assoc=0x0000);
+    
+    /**
+     * Get an array of file handles for the objects stored on the device
+     *
+     * @param storage_id Provide a way to filter by storage ID.
+     * @param format Provide a way to filter by format. PTP devices are not required to support filtering by format
+     * @param assoc  Provide a way to filter by association. PTP devices are not required to support filtering by association
+     * @param parser A pointer to a function to handle the data returned from the device. If left in the default value of NULL the data is thrown away as it is recieved.
+     * @return  A PTP response code
+     */
     uint16_t GetObjectHandles(uint32_t storage_id=0xffffffff, uint16_t format=0x0000, uint16_t assoc=0x0000, void *parser=NULL);
+
+    /**
+     * Get information about an object
+     *
+     * @param handle the file handle of the object to get information about.
+     * @return  A PTP response code
+     */
     uint16_t GetObjectInfo(uint32_t handle);
+    /**
+     * Ge a thumbnail for an object
+     *
+     * @param handle the file handle of the object.
+     * @param parser A pointer to a function to handle the data returned from the device. If left in the default value of NULL the data is thrown away as it is recieved.
+     * @return  A PTP response code
+     */
     uint16_t GetThumb(uint32_t handle, void *parser=NULL);
+    /**
+     *
+     * @param handle
+     * @param parser A pointer to a function to handle the data returned from the device. If left in the default value of NULL the data is thrown away as it is recieved.
+     * @return  A PTP response code
+     */
     uint16_t GetObject(uint32_t handle, void *parser=NULL);
+    /**
+     *
+     * @param parser A pointer to a function to handle the data returned from the device. If left in the default value of NULL the data is thrown away as it is recieved.
+     * @return  A PTP response code
+     */
     uint16_t GetStorageIDs(void *parser=NULL);
-    uint16_t GetStorageInfo(uint32_t storage_id, void *parser=NULL);
+
+    /**
+     * Obtain inforamtion about a storge.
+     *
+     * @param storage_id
+     * @return  A PTP response code
+     */
+    uint16_t GetStorageInfo(uint32_t storage_id);
+
+    /**
+     *
+     * @param handle
+     * @param storage_id
+     * @param parent
+     * @param new_handle
+     * @return  A PTP response code
+     */
     uint16_t CopyObject(uint32_t handle, uint32_t storage_id, uint32_t parent, uint32_t *new_handle);
+    /**
+     *
+     * @param handle
+     * @param format
+     * @return  A PTP response code
+     */
     uint16_t DeleteObject(uint32_t handle, uint16_t format);
+    /**
+     *
+     * @param handle
+     * @param attrib
+     * @return  A PTP response code
+     */
     uint16_t SetObjectProtection(uint32_t handle, uint16_t attrib);
+    /**
+     *
+     * @param handle
+     * @param storage_id
+     * @param parent
+     * @return  A PTP response code
+     */
     uint16_t MoveObject(uint32_t handle, uint32_t storage_id, uint32_t parent);
+    /**
+     *
+     * @param pcode
+     * @param parser A pointer to a function to handle the data returned from the device. If left in the default value of NULL the data is thrown away as it is recieved.
+     * @return  A PTP response code
+     */
     uint16_t GetDevicePropDesc(const uint16_t pcode, void *parser=NULL);
+    /**
+     *
+     * @param pcode
+     * @param parser A pointer to a function to handle the data returned from the device. If left in the default value of NULL the data is thrown away as it is recieved.
+     * @return  A PTP response code
+     */
     uint16_t GetDevicePropValue(const uint16_t pcode, void *parser=NULL);
+    /**
+     *
+     * @param pcode
+     * @param val
+     * @return  A PTP response code
+     */
     uint16_t SetDevicePropValue(uint16_t pcode, uint32_t val);
+    /**
+     *
+     * @param pcode
+     * @return  A PTP response code
+     */
     uint16_t ResetDevicePropValue(const uint16_t pcode);
+    /**
+     *
+     * @param storage_id
+     * @param fsformat
+     * @return  A PTP response code
+     */
     uint16_t FormatStore(uint32_t storage_id, uint32_t fsformat);
+    /**
+     *
+     * @param storage_id
+     * @param format
+     * @return  A PTP response code
+     */
     uint16_t InitiateCapture(uint32_t storage_id, uint16_t format);
+    /**
+     *
+     * @param storage_id
+     * @param format
+     * @return  A PTP response code
+     */
     uint16_t InitiateOpenCapture(uint32_t storage_id, uint16_t format);
+    
+    /**
+     *
+     * @param tran_id
+     * @return  A PTP response code
+     */
     uint16_t TerminateOpenCapture(uint32_t trans_id);
+    
+    /**
+     * Send the contents of the deviceInfo variable via serial communication
+     * @param none
+     * @return  void
+     */
     void DumpDeviceInfo(void);
+    
+    /**
+     * Send the contents of the objectInfo variable via serial communication
+     * @param none
+     * @return  void
+     */
     void DumpObjectInfo(void);
 
 protected:
@@ -156,6 +382,7 @@
     bool CheckEvent(void);
     static void ParseDeviceInfoDataBlock(void *ptp, uint8_t *buffer,uint16_t length); 
     static void ParseObjectInfoDataBlock(void *ptp, uint8_t *buffer,uint16_t length);
+    static void ParseStorageInfoDataBlock(void *ptp, uint8_t *buffer,uint16_t length);
     uint16_t Transaction(uint16_t operationCode, OperFlags *flags, uint32_t *params = NULL, void *pVoid = NULL);
 
 };