doc/DAEMON

   1 gPhoto Daemon
   2 --------------------------------------------------------------------
   3
   4 (note: this is a specification. it is not implemented!)
   5
   6 The gPhoto daemon uses the following protocol description. It provides an
   7 interactive way for program to talk and use gPhoto without needing to
   8 have any sort of C bindings.
   9
  10 This document needs better formatting (color syntax highlighting, structure)
  11
  12 Overview
  13 --------------------------------------------------------------------
  14 - The program provides gPhoto with a series of commands. gPhoto can
  15   also send message to the program through 4 notification commands.
  16
  17 - The arguments to a command are either a number or a string.
  18   If it's a string, you must put double-quotes around it.
  19
  20 - All commands to gPhoto are answered by an "OK" or "ERROR", possibly
  21   followed by additional data.
  22
  23 - Designed around simplicity and flexibility.
  24
  25 - Picture numbering begins at ZERO!
  26
  27 - Notification will come after issuing a command.
  28
  29 Example
  30 --------------------------------------------------------------------
  31
  32 '>' indicates commands from the program to gPhoto
  33 '<' indicates commands from gPhoto to the program
  34
  35 To put gphoto2 into a daemon mode, you must run it as "gphoto2 -S".
  36 You can open a pipe and then read/write to that file descriptor.
  37
  38 here is a session:
  39
  40 >       notification_set 1
  41 <       OK
  42 >       camera_list
  43 <       OK
  44 <       3
  45 <       Olympus D-220L
  46 <       Kodak DC210+
  47 <       Epson 650Z
  48 >       camera_Set "Epson 650Z"
  49 <       OK
  50 >       folder_list "/"
  51 <       OK
  52 <       5
  53 <       birthday/
  54 <       PIC0001.JPG
  55 <       PIC0002.JPG
  56 <       PIC0003.JPG
  57 <       PIC0004.JPG
  58 >       folder_set "/"
  59 <       OK
  60 >       file_count
  61 <       OK
  62 <       4
  63 >       file_get 0 "/home/scottf" "file0.jpg"
  64 <       confirm "Files exists. Overwrite?"
  65 >       confirm 1
  66 <       OK
  67 <       /home/scottf/file0.jpg
  68 >       file_get 1 "/home/scottf" "file1.jpg"
  69 <       OK
  70 <       /home/scottf/file1.jpg
  71 >       file_get 2 "/home/scottf" "file2.jpg"
  72 <       confirm "File exists. Overwrite?"
  73 >       confirm 0
  74 <       ERROR "Did not save /home/scottf/file2.jpg"
  75
  76 Commands to the gPhoto daemon
  77 --------------------------------------------------------------------
  78 setting_set key value
  79         Description: Saves the value of "key" as "value"
  80             Outputs: OK or ERROR
  81
  82             Example: > setting_set "foo" "bar"
  83                      < OK
  84
  85 setting_get key
  86         Description: Retrieves the value of "key"
  87             Outputs: OK or ERROR
  88                      if OK, followed by the value of the key
  89
  90             Example: > setting_get "foo"
  91                      < OK
  92                      < bar
  93
  94 notification_set number
  95         Description: Turns on (value = 1) or off (value = 0) notification
  96             Default: 0
  97             Outputs: OK or ERROR
  98
  99             Example: > debug_set 1
 100                      < OK
 101
 102
 103 debug_set number
 104         Description: Turns on (value = 1) or off (value = 0) debugging
 105             Default: 0
 106             Outputs: OK or ERROR
 107
 108             Example: > debug_set 1
 109                      < OK
 110
 111 camera_list
 112         Description: Lists the number of cameras and all the camera model names
 113             Outputs: OK or ERROR
 114                      if OK, followed by number of cameras, followed by camera models
 115
 116             Example: > camera_count
 117                      < OK
 118                      < 3
 119                      < Olympus D-220L
 120                      < Kodak DC210+
 121                      < Epson 650Z
 122 camera_set name
 123         Description: Sets the camera name as the chosen camera model
 124             Outputs: OK or ERROR
 125
 126             Example: > camera_set "Canon S10"
 127                      < OK
 128
 129 camera_abilities [name]
 130         Description: Determines the camera's abilities. The camera name is optional.
 131                      If not specified, uses currently set camera.
 132                      Please reference gphoto2-datatypes.h for available abilities and
 133                      descriptions.
 134             Outputs: OK or ERROR
 135                      if OK, followed by number of abilities, followed by abilities
 136
 137             Example: > camera_abilities "Olympus 3030Z"
 138                      < OK
 139                      < 13
 140                      < "usb"=1
 141                      < "parallel"=0
 142                      < "ieee1394"=0
 143                      < "serial"=1
 144                      < "speed"=9600
 145                      < "speed"=19200
 146                      < "speed"=38400
 147                      < "speed"=57600
 148                      < "speed"=115200
 149                      < "file_delete"=1
 150                      < "file_preview"=1
 151                      < "file_put"=0
 152                      < "file_capture"=1
 153                      < "config"=1
 154
 155 folder_list path
 156         Description: Display the contents of the folder path on the camera.
 157             Outputs: OK or ERROR
 158                      if OK, followed by number of entries, followed by the list.
 159                      an entry in the list has a trailing '/' if it is a folder.
 160
 161             Example: > folder_list "/"
 162                      < OK
 163                      < 4
 164                      < birthday/
 165                      < mountains/
 166                      < PIC001.JPG
 167                      < PIC002.JPG
 168
 169 folder_set path
 170         Description: Sets the current folder.
 171             Outputs: OK or ERROR
 172
 173             Example: > folder_set "/"
 174                      < OK
 175
 176 file_count
 177         Description: Determines the number of files (pictures, sounds, etc.) in the
 178                      current folder.
 179             Outputs: OK or ERROR
 180                      if OK, followed by number of files
 181
 182             Example: > file_count
 183                      < OK
 184                      < 12
 185
 186 file_get number [directory] [filename]
 187         Description: Downloads picture #number from the current folder
 188                         * if directory is specified, picture is saved to that directory using
 189                           the camera-recommended filename.
 190                         * if directory and filename is specified, picture is saved as filename
 191                           in the directory.
 192             Outputs: OK or ERROR
 193                      if OK:
 194                         if just number is specified:
 195                                 followed by mime-type, size of picture, and picture data
 196                         if directory and/or filename is specified:
 197                                 followed by path and filename of picture
 198
 199             Example: > file_get 12
 200                      < OK
 201                      < image/jpeg
 202                      < 98012
 203                      < image data ... . . . ....
 204                 or
 205                      > file_get 12 "/home/scottf/"
 206                      < OK
 207                      < /home/scottf/PIC0012.JPG
 208                 or
 209                      > file_get 12 "/home/scottf/" "picture12.jpg"
 210                      < OK
 211                      < /home/scottf/picture12.jpg
 212
 213 file_get_preview number [directory] [filename]
 214         Description: Downloads preview (thumbnail) #number from the current folder
 215                         * if directory is specified, preview is saved to that directory using
 216                           the camera-recommended filename.
 217                         * if directory and filename is specified, picture is saved as filename
 218                           in the directory.
 219             Outputs: OK or ERROR
 220                      if OK:
 221                         if just number is specified:
 222                                 followed by mime-type, size of preview, and preview data
 223                         if directory and/or filename is specified:
 224                                 followed by path and filename of preview
 225
 226             Example: > file_get_preview 12
 227                      < OK
 228                      < image/jpeg
 229                      < 12453
 230                      < image data ... . . . ....
 231                 or
 232                      > file_get_preview 12 "/home/scottf/"
 233                      < OK
 234                      < /home/scottf/THUMB0012.JPG
 235                 or
 236                      > file_get_preview 12 "/home/scottf/" "thumbnail12.jpg"
 237                      < OK
 238                      < /home/scottf/thumbnail12.jpg
 239
 240 file_put filename
 241         Description: Uploads the file specified by filename to the camera into the current folder
 242             Outputs: OK or ERROR
 243
 244             Example: > file_put /home/scottf/picture02.jpg
 245                      < OK
 246
 247 file_delete number
 248         Description: Deletes the file #number in the current folder
 249             Outputs: OK or ERROR
 250
 251             Example: > file_delete 12
 252                      < OK
 253 config_get
 254         Description: Gets a set of meta-widgets that describe camera configuration options.
 255                      (needs explanation on structure)
 256                         widget-type "label" value [min max step | choice]
 257                      * WINDOW and PAGE are containers. any widget coming after that is put into
 258                        the container.
 259                      * value is a number, except for TEXT (then value requires double-quotes)
 260             Outputs: OK or ERROR
 261                      if OK, followed by number of lines, followed by the meta-widgets
 262
 263             Example: > config_get
 264                      < OK
 265                      < 15
 266                      < WINDOW "Olympus Configuration"
 267                      < PAGE "Quality"
 268                      < RADIO "Resolution" 0 "Standard"
 269                      < RADIO "Resolution" 1 "High"
 270                      < RADIO "Resolution" 0 "Best"
 271                      < RADIO "Compression" 0 "None"
 272                      < RADIO "Compression" 0 "Low"
 273                      < RADIO "Compression" 1 "High"
 274                      < PAGE "Miscellaneous"
 275                      < RANGE "Zoom" 3.00
 276                      < TEXT "Camera Name" "Scott's Olympus D-220L"
 277                      < MENU "Flash Setting" 0 "Red-eye reduction"
 278                      < MENU "Flash Setting" 1 "Auto"
 279                      < MENU "Flash Setting" 0 "Forced"
 280                      < MENU "Flash Setting" 0 "Blind me"
 281
 282 config_set "label"=[choice|value] "label"=[choice|value] "label"=[choice|value] ...
 283         Description: Sets the camera configuration
 284                         * if RADIO or MENU, "label"="choice"
 285                         * for others, "label"=value
 286             Outputs: OK
 287
 288             Example: > config_set "Resolution"="Best" "Compression"="None" "Zoom"=0.00
 289                      < OK
 290
 291 capture_to_disk path [filename]
 292         Description: Causes camera to press the shutter, then download and save to disk.
 293                         filename is optional
 294             Outputs: OK or ERROR
 295                      if OK, followed by picture filename
 296
 297             Example: > capture_to_disk "/home/scottf"
 298                      < OK
 299                      < /home/scottf/PIC00012.JPG
 300                 or
 301                      > capture_to_disk "/home/scottf" "livepicture.jpg"
 302                      < OK
 303                      < /home/scottflivepicture.jpg
 304
 305 about
 306         Description: Displays information about the camera library
 307             Outputs: OK or ERROR
 308                      if OK, followed by number of lines, then camera library information
 309
 310             Example: > about
 311                      < OK
 312                      < 3
 313                      < Scott <scottf@unr.edu>
 314                      < Camera library for foo-bar cameras
 315                      < These cameras are kinda silly.
 316
 317 manual
 318         Description: Displays the camera library manual
 319             Outputs: OK or ERROR
 320                      if OK, followed by number of lines, then camera library manual
 321
 322             Example: > manual
 323                      < OK
 324                      < 5
 325                      < This camera library is a good library.
 326                      < It does not support capturing image though.
 327                      < The company that make the camera helped
 328                      < by providing information about the communication
 329                      < protocol.
 330
 331 summary
 332         Description: Displays the camera summary
 333             Outputs: OK or ERROR
 334                      if OK, followed by number of lines, then camera summary
 335
 336             Example: > summary
 337                      < OK
 338                      < 3
 339                      < Battery Percent = 65%
 340                      < Free memory is 31Meg
 341                      < My height is around 6'4"
 342
 343 gPhoto notifications
 344 --------------------------------------------------------------------
 345 These depend on whether or not "notification_set" has been called.
 346 By default, they are turned off. Use "notification_set 1" to turn them
 347 on.
 348
 349 progress number
 350         Description: Should display the percent done in the current operation
 351            Response: none
 352             Example: < progress 50
 353
 354 message "string"
 355         Description: Should display a message to the user (pop-up window)
 356            Response: none
 357
 358             Example: < message "Don't you want to be a pepper too?"
 359
 360 status "string"
 361         Description: Should display the status to the user (status bar)
 362            Response: none
 363
 364             Example: < status "Done with current operation."
 365
 366 confirm "string"
 367         Description: Should display a "yes" or "no" confirmation box to the user.
 368            Response: confirm 0 (no), confirm 1 (yes), or ERROR
 369
 370             Example: < confirm "Do you want to delete that file?"
 371                      > confirm 1
 372                      (gPhoto will not answer this).