libmtp 1.1.11

chdk_ptp.h

00001 #ifndef __CHDK_PTP_H
00002 #define __CHDK_PTP_H
00003 
00004 // CHDK PTP protocol interface (can also be used in client PTP programs)
00005 
00006 // Note: used in modules and platform independent code. 
00007 // Do not add platform dependent stuff in here (#ifdef/#endif compile options or camera dependent values)
00008 
00009 #define PTP_CHDK_VERSION_MAJOR 2  // increase only with backwards incompatible changes (and reset minor)
00010 #define PTP_CHDK_VERSION_MINOR 6  // increase with extensions of functionality
00011                                   // minor > 1000 for development versions
00012 
00013 /*
00014 protocol version history
00015 0.1 - initial proposal from mweerden, + luar
00016 0.2 - Added ScriptStatus and ScriptSupport, based on work by ultimA
00017 1.0 - removed old script result code (luar), replace with message system
00018 2.0 - return PTP_CHDK_TYPE_TABLE for tables instead of TYPE_STRING, allow return of empty strings
00019 2.1 - experimental live view, not formally released
00020 2.2 - live view (work in progress)
00021 2.3 - live view - released in 1.1
00022 2.4 - live view protocol 2.1
00023 2.5 - remote capture
00024 2.6 - script execution flags
00025 */
00026 
00027 #define PTP_OC_CHDK 0x9999
00028 
00029 // N.B.: unused parameters should be set to 0
00030 //enum ptp_chdk_command {
00031 enum PTP_CHDK_Command {
00032   PTP_CHDK_Version = 0,     // return param1 is major version number
00033                             // return param2 is minor version number
00034   PTP_CHDK_GetMemory,       // param2 is base address (not NULL; circumvent by taking 0xFFFFFFFF and size+1)
00035                             // param3 is size (in bytes)
00036                             // return data is memory block
00037   PTP_CHDK_SetMemory,       // param2 is address
00038                             // param3 is size (in bytes)
00039                             // data is new memory block
00040   PTP_CHDK_CallFunction,    // data is array of function pointer and 32 bit int arguments (max: 10 args prior to protocol 2.5)
00041                             // return param1 is return value
00042   PTP_CHDK_TempData,        // data is data to be stored for later
00043                             // param2 is for the TD flags below
00044   PTP_CHDK_UploadFile,      // data is 4-byte length of filename, followed by filename and contents
00045   PTP_CHDK_DownloadFile,    // preceded by PTP_CHDK_TempData with filename
00046                             // return data are file contents
00047   PTP_CHDK_ExecuteScript,   // data is script to be executed
00048                             // param2 is language of script
00049                             //  in proto 2.6 and later, language is the lower byte, rest is used for PTP_CHDK_SCRIPT_FL* flags
00050                             // return param1 is script id, like a process id
00051                             // return param2 is status from ptp_chdk_script_error_type
00052   PTP_CHDK_ScriptStatus,    // Script execution status
00053                             // return param1 bits
00054                             // PTP_CHDK_SCRIPT_STATUS_RUN is set if a script running, cleared if not
00055                             // PTP_CHDK_SCRIPT_STATUS_MSG is set if script messages from script waiting to be read
00056                             // all other bits and params are reserved for future use
00057   PTP_CHDK_ScriptSupport,   // Which scripting interfaces are supported in this build
00058                             // param1 CHDK_PTP_SUPPORT_LUA is set if lua is supported, cleared if not
00059                             // all other bits and params are reserved for future use
00060   PTP_CHDK_ReadScriptMsg,   // read next message from camera script system
00061                             // return param1 is chdk_ptp_s_msg_type
00062                             // return param2 is message subtype:
00063                             //   for script return and users this is ptp_chdk_script_data_type
00064                             //   for error ptp_chdk_script_error_type
00065                             // return param3 is script id of script that generated the message
00066                             // return param4 is length of the message data. 
00067                             // return data is message.
00068                             // A minimum of 1 bytes of zeros is returned if the message has no data (empty string or type NONE)
00069   PTP_CHDK_WriteScriptMsg,  // write a message for scripts running on camera
00070                             // input param2 is target script id, 0=don't care. Messages for a non-running script will be discarded
00071                             // data length is handled by ptp data phase
00072                             // input messages do not have type or subtype, they are always a string destined for the script (similar to USER/string)
00073                             // output param1 is ptp_chdk_script_msg_status
00074   PTP_CHDK_GetDisplayData,  // Return camera display data
00075                             // This is defined as separate sub protocol in live_view.h
00076                             // Changes to the sub-protocol will always be considered a minor change to the main protocol
00077                             //  param2 bitmask of data
00078                             //  output param1 = total size of data
00079                             //  return data is protocol information, frame buffer descriptions and selected display data
00080                             //  Currently a data phase is always returned. Future versions may define other behavior 
00081                             //  for values in currently unused parameters.
00082   // Direct image capture over USB.
00083   // Use lua get_usb_capture_support for available data types, lua init_usb_capture for setup
00084   PTP_CHDK_RemoteCaptureIsReady, // Check if data is available
00085                                  // return param1 is status 
00086                                  //  0 = not ready
00087                                  //  0x10000000 = remote capture not initialized
00088                                  //  otherwise bitmask of PTP_CHDK_CAPTURE_* datatypes
00089                                  // return param2 is image number
00090   PTP_CHDK_RemoteCaptureGetData  // retrieve data
00091                                  // param2 is bit indicating data type to get
00092                                  // return param1 is length
00093                                  // return param2 more chunks available?
00094                                  //  0 = no more chunks of selected format
00095                                  // return param3 seek required to pos (-1 = no seek)
00096 };
00097 
00098 // data types as used by ReadScriptMessage
00099 enum ptp_chdk_script_data_type {
00100   PTP_CHDK_TYPE_UNSUPPORTED = 0, // type name will be returned in data
00101   PTP_CHDK_TYPE_NIL,
00102   PTP_CHDK_TYPE_BOOLEAN,
00103   PTP_CHDK_TYPE_INTEGER,
00104   PTP_CHDK_TYPE_STRING, // Empty strings are returned with length=0
00105   PTP_CHDK_TYPE_TABLE,  // tables are converted to a string by usb_msg_table_to_string, 
00106                         // this function can be overridden in lua to change the format
00107                         // the string may be empty for an empty table
00108 };
00109 
00110 // TempData flags
00111 #define PTP_CHDK_TD_DOWNLOAD  0x1  // download data instead of upload
00112 #define PTP_CHDK_TD_CLEAR     0x2  // clear the stored data; with DOWNLOAD this
00113                                    // means first download, then clear and
00114                                    // without DOWNLOAD this means no uploading,
00115                                    // just clear
00116 
00117 // Script Languages - for execution only lua is supported for now
00118 #define PTP_CHDK_SL_LUA    0
00119 #define PTP_CHDK_SL_UBASIC 1
00120 #define PTP_CHDK_SL_MASK 0xFF
00121 
00122 /* standard message chdkptp sends */
00123 #define PTP_CHDK_LUA_SERIALIZE "\n\
00124 serialize_r = function(v,opts,r,seen,depth)\n\
00125         local vt = type(v)\n\
00126         if vt == 'nil' or  vt == 'boolean' or vt == 'number' then\n\
00127                 table.insert(r,tostring(v))\n\
00128                 return\n\
00129         end\n\
00130         if vt == 'string' then\n\
00131                 table.insert(r,string.format('%q',v))\n\
00132                 return\n\
00133         end\n\
00134         if vt == 'table' then\n\
00135                 if not depth then\n\
00136                         depth = 1\n\
00137                 end\n\
00138                 if depth >= opts.maxdepth then\n\
00139                         error('serialize: max depth')\n\
00140                 end\n\
00141                 if not seen then\n\
00142                         seen={}\n\
00143                 elseif seen[v] then\n\
00144                         if opts.err_cycle then\n\
00145                                 error('serialize: cycle')\n\
00146                         else\n\
00147                                 table.insert(r,'\"cycle:'..tostring(v)..'\"')\n\
00148                                 return\n\
00149                         end\n\
00150                 end\n\
00151                 seen[v] = true;\n\
00152                 table.insert(r,'{')\n\
00153                 for k,v1 in pairs(v) do\n\
00154                         if opts.pretty then\n\
00155                                 table.insert(r,'\\n'..string.rep(' ',depth))\n\
00156                         end\n\
00157                         if type(k) == 'string' and string.match(k,'^[_%a][%a%d_]*$') then\n\
00158                                 table.insert(r,k)\n\
00159                         else\n\
00160                                 table.insert(r,'[')\n\
00161                                 serialize_r(k,opts,r,seen,depth+1)\n\
00162                                 table.insert(r,']')\n\
00163                         end\n\
00164                         table.insert(r,'=')\n\
00165                         serialize_r(v1,opts,r,seen,depth+1)\n\
00166                         table.insert(r,',')\n\
00167                 end\n\
00168                 if opts.pretty then\n\
00169                         table.insert(r,'\\n'..string.rep(' ',depth-1))\n\
00170                 end\n\
00171                 table.insert(r,'}')\n\
00172                 return\n\
00173         end\n\
00174         if opts.err_type then\n\
00175                 error('serialize: unsupported type ' .. vt, 2)\n\
00176         else\n\
00177                 table.insert(r,'\"'..tostring(v)..'\"')\n\
00178         end\n\
00179 end\n\
00180 serialize_defaults = {\n\
00181         maxdepth=10,\n\
00182         err_type=true,\n\
00183         err_cycle=true,\n\
00184         pretty=false,\n\
00185 }\n\
00186 function serialize(v,opts)\n\
00187         if opts then\n\
00188                 for k,v in pairs(serialize_defaults) do\n\
00189                         if not opts[k] then\n\
00190                                 opts[k]=v\n\
00191                         end\n\
00192                 end\n\
00193         else\n\
00194                 opts=serialize_defaults\n\
00195         end\n\
00196         local r={}\n\
00197         serialize_r(v,opts,r)\n\
00198         return table.concat(r)\n\
00199 end\n\
00200 \n\
00201 usb_msg_table_to_string=serialize\n"
00202 
00203 
00204 // bit flags for script start
00205 #define PTP_CHDK_SCRIPT_FL_NOKILL           0x100 // if script is running return error instead of killing
00206 #define PTP_CHDK_SCRIPT_FL_FLUSH_CAM_MSGS   0x200 // discard existing cam->host messages before starting
00207 #define PTP_CHDK_SCRIPT_FL_FLUSH_HOST_MSGS  0x400 // discard existing host->cam messages before starting
00208 
00209 // bit flags for script status
00210 #define PTP_CHDK_SCRIPT_STATUS_RUN   0x1 // script running
00211 #define PTP_CHDK_SCRIPT_STATUS_MSG   0x2 // messages waiting
00212 // bit flags for scripting support
00213 #define PTP_CHDK_SCRIPT_SUPPORT_LUA  0x1
00214 
00215 
00216 // bit flags for remote capture
00217 // used to select and also to indicate available data in PTP_CHDK_RemoteCaptureIsReady
00218 /*
00219 Full jpeg file. Note supported on all cameras, use Lua get_usb_capture_support to check
00220 */
00221 #define PTP_CHDK_CAPTURE_JPG    0x1 
00222 
00223 /*
00224 Raw framebuffer data, in camera native format.
00225 A subset of rows may be requested in init_usb_capture.
00226 */
00227 #define PTP_CHDK_CAPTURE_RAW    0x2
00228 
00229 /*
00230 DNG header. 
00231 The header will be DNG version 1.3
00232 Does not include image data, clients wanting to create a DNG file should also request RAW
00233 Raw data for all known cameras will be packed, little endian. Client is responsible for
00234 reversing the byte order if creating a DNG.
00235 Can requested without RAW to get sensor dimensions, exif values etc.
00236 
00237 ifd 0 specifies a 128x96 RGB thumbnail, 4 byte aligned following the header
00238 client is responsible for generating thumbnail data.
00239 
00240 ifd 0 subifd 0 specifies the main image
00241 The image dimensions always contain the full sensor dimensions, if a sub-image was requested
00242 with init_usb_capture, the client is responsible for padding the data to the full image or
00243 adjusting dimensions.
00244 
00245 Bad pixels will not be patched, but DNG opcodes will specify how to patch them
00246 */
00247 #define PTP_CHDK_CAPTURE_DNGHDR 0x4  
00248 
00249 // status from PTP_CHDK_RemoteCaptureIsReady if capture not enabled
00250 #define PTP_CHDK_CAPTURE_NOTSET 0x10000000
00251 
00252 // message types
00253 enum ptp_chdk_script_msg_type {
00254     PTP_CHDK_S_MSGTYPE_NONE = 0, // no messages waiting
00255     PTP_CHDK_S_MSGTYPE_ERR,      // error message
00256     PTP_CHDK_S_MSGTYPE_RET,      // script return value
00257     PTP_CHDK_S_MSGTYPE_USER,     // message queued by script
00258 // TODO chdk console data ?
00259 };
00260 
00261 // error subtypes for PTP_CHDK_S_MSGTYPE_ERR and script startup status
00262 enum ptp_chdk_script_error_type {
00263     PTP_CHDK_S_ERRTYPE_NONE = 0,
00264     PTP_CHDK_S_ERRTYPE_COMPILE,
00265     PTP_CHDK_S_ERRTYPE_RUN,
00266     // the following are for ExecuteScript status only, not message types
00267     PTP_CHDK_S_ERR_SCRIPTRUNNING = 0x1000, // script already running with NOKILL
00268 };
00269 
00270 // message status
00271 enum ptp_chdk_script_msg_status {
00272     PTP_CHDK_S_MSGSTATUS_OK = 0, // queued ok
00273     PTP_CHDK_S_MSGSTATUS_NOTRUN, // no script is running
00274     PTP_CHDK_S_MSGSTATUS_QFULL,  // queue is full
00275     PTP_CHDK_S_MSGSTATUS_BADID,  // specified ID is not running
00276 };
00277 
00278 #endif // __CHDK_PTP_H