include/pnd_discovery.h

   1
   2 #ifndef h_pnd_discovery_h
   3 #define h_pnd_discovery_h
   4
   5 #ifdef __cplusplus
   6 extern "C" {
   7 #endif
   8
   9 // this code is for doing the application discovery against a given directory and its children (ie: this
  10 // code could be called on appliction startup, or as a result of media eject/insert, and so forth.)
  11
  12 /* disco_search() will walk the given search path (one or more paths, colon separated) in order left to
  13  * right; as PXML's are found, basic analysis is performed to verfy validity. A list of valid applications
  14  * is returned, the union of all matches in the search path
  15  * If no matches are found, NULL is returned (to save you deleting the container)
  16  * overridespath may be NULL if you do not wish to search for pxml overrides
  17  */
  18 pnd_box_handle pnd_disco_search ( char *searchpath, char *overridespath );
  19 pnd_box_handle pnd_disco_file ( char *path, char *filename ); // should you wish to 'discover' one .pnd-file
  20
  21 /* pnd_disco_t describes a given entry found by the discovery code; ie: the containers key is the path to
  22  * the PXML file (since this is relatively unique), with the fields below detailing the executable path,
  23  * application name, unique-id and so on
  24  *
  25  * NOTE: this struct is dynamicly populated; you are responsible for invoking the destroy() function to
  26  * kill its contents, and the pnt_box_destroy() to kill the container at the end
  27  *
  28  * NOTE: The PXML path (or .pnd file path in bundle files) is used as a key since it is unique. The
  29  * application 'unique id' will be unique for a given app, but that app could be in multiple directories
  30  * or on multiple SD cards or wifi or whatever, so only the mounted path is truly unique. The key
  31  * is only used internally so the consumer can refer to multiple versions of the same app without
  32  * confusion.. it is not displayed. So no big deal.
  33  */
  34
  35 typedef enum {
  36   pnd_object_type_unknown = 0,
  37   pnd_object_type_directory,
  38   pnd_object_type_pnd,
  39   pnd_object_type_max
  40 } pnd_object_type_t;
  41
  42 // another struct? Have always intended discovery_t to have minimal members.. just enough to lead to an
  43 // application (PXML, xecutable, name); if the apps want more details, they can use the pnd_pxml code to
  44 // fetch the full PXML and get all the details. But I think we got out of control here :)
  45 // NOTE: We really need to rework disco-t so it can include non-english titles/desc; perhaps more info as optional,
  46 //   or a name/value pairing system so it can have extra data in it, without a complex structure.
  47 #define PND_DISCO_FLAG_OVR 1       // An ovr file was found for this app (not per subapp, just per .pnd)
  48 #define PND_DISCO_GENERATED 2      // This disco is 'faux', made up and not reflecting a real 'pnd file'
  49 #define PND_DISCO_CUSTOM1 (1<<30)  // An app may make use of this bitflag safely
  50 #define PND_DISCO_CUSTOM2 (1<<31)  // An app may make use of this bitflag safely
  51 typedef struct {
  52   // base
  53   unsigned char object_type;   // see enum above
  54   char *object_path;           // directory containing pnd or PXML.xml (does not include filename)
  55   char *object_filename;       // filename within object_path of the app: the PXML.xml or awesomeapp.pnd file itself
  56   unsigned int pnd_icon_pos;   // offset to the byte after end of PXML in a pnd file (should be icon if present)
  57   unsigned char subapp_number; // # of app within PXML (ie: 0, 1, 2, 3, up to the number of apps within the PXML)
  58   unsigned int object_flags;   // see PND_DISCO_ bitmasks above
  59   // strdup'd from PXML -- hey, who was the idiot who thought it was a reat idea not to just re-use the pxml-struct?
  60   char *package_id;
  61   char *title_en;
  62   char *desc_en;
  63   char *unique_id;
  64   char *appdata_dirname;       // preferred dir name for appdata; if missing, use unique-id
  65   char *icon;
  66   char *exec;
  67   char *execargs;
  68   char *clockspeed;
  69   char *startdir;
  70   char *option_no_x11;
  71   char *main_category;
  72   char *main_category1;
  73   char *main_category2;
  74   char *alt_category;
  75   char *alt_category1;
  76   char *alt_category2;
  77   char *preview_pic1;
  78   char *preview_pic2;
  79   char *mkdir_sp;
  80   char *info_name;      // should be a struct..
  81   char *info_filename;
  82   char *info_type;
  83 } pnd_disco_t;
  84
  85 void pnd_disco_destroy ( pnd_disco_t *p ); // a function name that simply could not be avoided
  86
  87 // TODO: A way to release the disco-lists and reclaim RAM :)
  88
  89 #ifdef __cplusplus
  90 } /* "C" */
  91 #endif
  92
  93 #endif