source: trunk/core/ptp.h @ 3421

Revision 3268, 9.9 KB checked in by reyalp, 4 months ago (diff)

ptp - adjust PTP_CHDK_ExecuteScript to return only a status without message if a script is running, don't increment script_id

  • Property svn:eol-style set to native
Line 
1#ifndef __CHDK_PTP_H
2#define __CHDK_PTP_H
3
4// CHDK PTP protocol interface (can also be used in client PTP programs)
5
6// Note: used in modules and platform independent code.
7// Do not add platform dependent stuff in here (#ifdef/#endif compile options or camera dependent values)
8
9#define PTP_CHDK_VERSION_MAJOR 2  // increase only with backwards incompatible changes (and reset minor)
10#define PTP_CHDK_VERSION_MINOR 6  // increase with extensions of functionality
11                                  // minor > 1000 for development versions
12
13/*
14protocol version history
150.1 - initial proposal from mweerden, + luar
160.2 - Added ScriptStatus and ScriptSupport, based on work by ultimA
171.0 - removed old script result code (luar), replace with message system
182.0 - return PTP_CHDK_TYPE_TABLE for tables instead of TYPE_STRING, allow return of empty strings
192.1 - experimental live view, not formally released
202.2 - live view (work in progress)
212.3 - live view - released in 1.1
222.4 - live view protocol 2.1
232.5 - remote capture
242.6 - script execution flags
25*/
26
27#define PTP_OC_CHDK 0x9999
28
29// N.B.: unused parameters should be set to 0
30enum ptp_chdk_command {
31  PTP_CHDK_Version = 0,     // return param1 is major version number
32                            // return param2 is minor version number
33  PTP_CHDK_GetMemory,       // param2 is base address (not NULL; circumvent by taking 0xFFFFFFFF and size+1)
34                            // param3 is size (in bytes)
35                            // return data is memory block
36  PTP_CHDK_SetMemory,       // param2 is address
37                            // param3 is size (in bytes)
38                            // data is new memory block
39  PTP_CHDK_CallFunction,    // data is array of function pointer and 32 bit int arguments (max: 10 args prior to protocol 2.5)
40                            // return param1 is return value
41  PTP_CHDK_TempData,        // data is data to be stored for later
42                            // param2 is for the TD flags below
43  PTP_CHDK_UploadFile,      // data is 4-byte length of filename, followed by filename and contents
44  PTP_CHDK_DownloadFile,    // preceded by PTP_CHDK_TempData with filename
45                            // return data are file contents
46  PTP_CHDK_ExecuteScript,   // data is script to be executed
47                            // param2 is language of script
48                            //  in proto 2.6 and later, language is the lower byte, rest is used for PTP_CHDK_SCRIPT_FL* flags
49                            // return param1 is script id, like a process id
50                            // return param2 is status from ptp_chdk_script_error_type
51  PTP_CHDK_ScriptStatus,    // Script execution status
52                            // return param1 bits
53                            // PTP_CHDK_SCRIPT_STATUS_RUN is set if a script running, cleared if not
54                            // PTP_CHDK_SCRIPT_STATUS_MSG is set if script messages from script waiting to be read
55                            // all other bits and params are reserved for future use
56  PTP_CHDK_ScriptSupport,   // Which scripting interfaces are supported in this build
57                            // param1 CHDK_PTP_SUPPORT_LUA is set if lua is supported, cleared if not
58                            // all other bits and params are reserved for future use
59  PTP_CHDK_ReadScriptMsg,   // read next message from camera script system
60                            // return param1 is chdk_ptp_s_msg_type
61                            // return param2 is message subtype:
62                            //   for script return and users this is ptp_chdk_script_data_type
63                            //   for error ptp_chdk_script_error_type
64                            // return param3 is script id of script that generated the message
65                            // return param4 is length of the message data.
66                            // return data is message.
67                            // A minimum of 1 bytes of zeros is returned if the message has no data (empty string or type NONE)
68  PTP_CHDK_WriteScriptMsg,  // write a message for scripts running on camera
69                            // input param2 is target script id, 0=don't care. Messages for a non-running script will be discarded
70                            // data length is handled by ptp data phase
71                            // input messages do not have type or subtype, they are always a string destined for the script (similar to USER/string)
72                            // output param1 is ptp_chdk_script_msg_status
73  PTP_CHDK_GetDisplayData,  // Return camera display data
74                            // This is defined as separate sub protocol in live_view.h
75                            // Changes to the sub-protocol will always be considered a minor change to the main protocol
76                            //  param2 bitmask of data
77                            //  output param1 = total size of data
78                            //  return data is protocol information, frame buffer descriptions and selected display data
79                            //  Currently a data phase is always returned. Future versions may define other behavior
80                            //  for values in currently unused parameters.
81  // Direct image capture over USB.
82  // Use lua get_usb_capture_support for available data types, lua init_usb_capture for setup
83  PTP_CHDK_RemoteCaptureIsReady, // Check if data is available
84                                 // return param1 is status
85                                 //  0 = not ready
86                                 //  0x10000000 = remote capture not initialized
87                                 //  otherwise bitmask of PTP_CHDK_CAPTURE_* datatypes
88                                 // return param2 is image number
89  PTP_CHDK_RemoteCaptureGetData  // retrieve data
90                                 // param2 is bit indicating data type to get
91                                 // return param1 is length
92                                 // return param2 more chunks available?
93                                 //  0 = no more chunks of selected format
94                                 // return param3 seek required to pos (-1 = no seek)
95};
96
97// data types as used by ReadScriptMessage
98enum ptp_chdk_script_data_type {
99  PTP_CHDK_TYPE_UNSUPPORTED = 0, // type name will be returned in data
100  PTP_CHDK_TYPE_NIL,
101  PTP_CHDK_TYPE_BOOLEAN,
102  PTP_CHDK_TYPE_INTEGER,
103  PTP_CHDK_TYPE_STRING, // Empty strings are returned with length=0
104  PTP_CHDK_TYPE_TABLE,  // tables are converted to a string by usb_msg_table_to_string,
105                        // this function can be overridden in lua to change the format
106                        // the string may be empty for an empty table
107};
108
109// TempData flags
110#define PTP_CHDK_TD_DOWNLOAD  0x1  // download data instead of upload
111#define PTP_CHDK_TD_CLEAR     0x2  // clear the stored data; with DOWNLOAD this
112                                   // means first download, then clear and
113                                   // without DOWNLOAD this means no uploading,
114                                   // just clear
115
116// Script Languages - for execution only lua is supported for now
117#define PTP_CHDK_SL_LUA    0
118#define PTP_CHDK_SL_UBASIC 1
119#define PTP_CHDK_SL_MASK 0xFF
120
121// bit flags for script start
122#define PTP_CHDK_SCRIPT_FL_NOKILL           0x100 // if script is running return error instead of killing
123#define PTP_CHDK_SCRIPT_FL_FLUSH_CAM_MSGS   0x200 // discard existing cam->host messages before starting
124#define PTP_CHDK_SCRIPT_FL_FLUSH_HOST_MSGS  0x400 // discard existing host->cam messages before starting
125
126// bit flags for script status
127#define PTP_CHDK_SCRIPT_STATUS_RUN   0x1 // script running
128#define PTP_CHDK_SCRIPT_STATUS_MSG   0x2 // messages waiting
129// bit flags for scripting support
130#define PTP_CHDK_SCRIPT_SUPPORT_LUA  0x1
131
132
133// bit flags for remote capture
134// used to select and also to indicate available data in PTP_CHDK_RemoteCaptureIsReady
135/*
136Full jpeg file. Note supported on all cameras, use Lua get_usb_capture_support to check
137*/
138#define PTP_CHDK_CAPTURE_JPG    0x1
139
140/*
141Raw framebuffer data, in camera native format.
142A subset of rows may be requested in init_usb_capture.
143*/
144#define PTP_CHDK_CAPTURE_RAW    0x2
145
146/*
147DNG header.
148The header will be DNG version 1.3
149Does not include image data, clients wanting to create a DNG file should also request RAW
150Raw data for all known cameras will be packed, little endian. Client is responsible for
151reversing the byte order if creating a DNG.
152Can requested without RAW to get sensor dimensions, exif values etc.
153
154ifd 0 specifies a 128x96 RGB thumbnail, 4 byte aligned following the header
155client is responsible for generating thumbnail data.
156
157ifd 0 subifd 0 specifies the main image
158The image dimensions always contain the full sensor dimensions, if a sub-image was requested
159with init_usb_capture, the client is responsible for padding the data to the full image or
160adjusting dimensions.
161
162Bad pixels will not be patched, but DNG opcodes will specify how to patch them
163*/
164#define PTP_CHDK_CAPTURE_DNGHDR 0x4 
165
166// status from PTP_CHDK_RemoteCaptureIsReady if capture not enabled
167#define PTP_CHDK_CAPTURE_NOTSET 0x10000000
168
169// message types
170enum ptp_chdk_script_msg_type {
171    PTP_CHDK_S_MSGTYPE_NONE = 0, // no messages waiting
172    PTP_CHDK_S_MSGTYPE_ERR,      // error message
173    PTP_CHDK_S_MSGTYPE_RET,      // script return value
174    PTP_CHDK_S_MSGTYPE_USER,     // message queued by script
175// TODO chdk console data ?
176};
177
178// error subtypes for PTP_CHDK_S_MSGTYPE_ERR and script startup status
179enum ptp_chdk_script_error_type {
180    PTP_CHDK_S_ERRTYPE_NONE = 0,
181    PTP_CHDK_S_ERRTYPE_COMPILE,
182    PTP_CHDK_S_ERRTYPE_RUN,
183    // the following are for ExecuteScript status only, not message types
184    PTP_CHDK_S_ERR_SCRIPTRUNNING = 0x1000, // script already running with NOKILL
185};
186
187// message status
188enum ptp_chdk_script_msg_status {
189    PTP_CHDK_S_MSGSTATUS_OK = 0, // queued ok
190    PTP_CHDK_S_MSGSTATUS_NOTRUN, // no script is running
191    PTP_CHDK_S_MSGSTATUS_QFULL,  // queue is full
192    PTP_CHDK_S_MSGSTATUS_BADID,  // specified ID is not running
193};
194
195#endif // __CHDK_PTP_H
Note: See TracBrowser for help on using the repository browser.