X11 Work Bench Toolkit  1.0
conf_help.h
Go to the documentation of this file.
1 // __ _ _ _ //
3 // ___ ___ _ __ / _| | |__ ___ | | _ __ | |__ //
4 // / __|/ _ \ | '_ \ | |_ | '_ \ / _ \| || '_ \ | '_ \ //
5 // | (__| (_) || | | || _| | | | || __/| || |_) |_| | | | //
6 // \___|\___/ |_| |_||_|_____|_| |_| \___||_|| .__/(_)_| |_| //
7 // |_____| |_| //
8 // //
9 // helper API for 'conf' files (global and per-user) //
10 // //
12 
13 /*****************************************************************************
14 
15  X11workbench - X11 programmer's 'work bench' application and toolkit
16  Copyright (c) 2010-2016 by Bob Frazier (aka 'Big Bad Bombastic Bob')
17  all rights reserved
18 
19  DISCLAIMER: The X11workbench application and toolkit software are supplied
20  'as-is', with no warranties, either implied or explicit.
21  Any claims to alleged functionality or features should be
22  considered 'preliminary', and might not function as advertised.
23 
24  BSD-like license:
25 
26  There is no restriction as to what you can do with this software, so long
27  as you include the above copyright notice and DISCLAIMER for any distributed
28  work that is equal to or derived from this one, along with this paragraph
29  that explains the terms of the license if the source is also being made
30  available. A "derived work" describes a work that uses a significant portion
31  of the source files or algorithms that are included with this one.
32  Specifically excluded from this are files that were generated by the software,
33  or anything that is included with the software that is part of another package
34  (such as files that were created or added during the 'configure' process).
35  Specifically included is the use of part or all of any of the X11 workbench
36  toolkit source or header files in your distributed application. If you do not
37  ship the source, the above copyright statement is still required to be placed
38  in a reasonably prominent place, such as documentation, splash screens, and/or
39  'about the application' dialog boxes.
40 
41  Use and distribution are in accordance with GPL, LGPL, and/or the above
42  BSD-like license. See COPYING and README files for more information.
43 
44 
45  Additional information at http://sourceforge.net/projects/X11workbench
46 
47 ******************************************************************************/
48 
49 
50 // conf file format:
51 // [section header]
52 // data identifier=data value
53 
79 #ifndef CONF_HELPER_H_INCLUDED
80 #define CONF_HELPER_H_INCLUDED
81 
82 #include "platform_helper.h" /* this also includes the X11 headers */
83 
84 #ifdef __cplusplus
85 extern "C" {
86 #endif // __cplusplus
87 
88 
89 #ifndef GLOBAL_PATH /* this can be defined by the config script */
90 #warning "GLOBAL_PATH not defined, assuming /usr/local/etc"
91 #define GLOBAL_PATH "/usr/local/etc"
92 #endif // GLOBAL_PATH
93 
94 #ifndef GLOBAL_XPATH /* this can be defined by the config script */
95 #ifdef __FreeBSD__
96 #warning "GLOBAL_XPATH not defined, assuming /usr/local/etc/X11"
97 #define GLOBAL_XPATH "/usr/local/etc/X11"
98 #else // others whose distros don't consider 'X11' to be in '/usr/local'
99 #warning "GLOBAL_XPATH not defined, assuming /etc/X11"
100 #define GLOBAL_XPATH "/etc/X11"
101 #endif // __FreeBSD__, others
102 #endif // GLOBAL_XPATH
103 
104 #define LOCAL_PATH "~/"
105 #define LOCAL_CONF_NAME "settings" /* local conf name will be ~/.appname/settings.conf, or if that is not possible, ~/appname.conf */
106 
107 #define CH_OPEN_TIMEOUT 5000 /* wait up to 5000 milliseconds before timing out */
108 
109 
113 #define CH_FLAGS_DEFAULT 0
114 #define CH_FLAGS_GLOBAL 0x1
115 #define CH_FLAGS_WRITE 0x2
117 #define CHPARSEXML_DEFAULT 0
118 #define CHPARSEXML_PAREN 1
119 #define CHPARSEXML_BRACKET 2
136 void CHRegisterArgs(int argc, char **argv); // call in 'main'
137 
145 void CHOnExit(void);
146 
156 const char * const *CHGetArgV(void);
157 
167 int CHGetArgC(void);
168 
183 int CHGetResourceString(Display *pDisplay,const char *szIdentifier, char *szData, int cbData);
184 
197 int CHGetResourceInt(Display *pDisplay,const char *szIdentifier);
198 
199 
200 
202 // configuration file management
204 
219 void * CHOpenConfFile(const char *szAppName, int iFlags);
220 
232 void CHCloseConfFile(void * hFile);
233 
244 void CHDestroyConfFile(void * hFile);
245 
262 int CHGetConfFileString(void * hFile, const char *szSection,
263  const char *szIdentifier, char *szData, int cbData);
264 
279 int CHWriteConfFileString(void * hFile, const char *szSection,
280  const char *szIdentifier, const char *szData);
281 
282 
298 int CHGetConfFileInt(void * hFile, const char *szSection, const char *szIdentifier);
299 
314 int CHWriteConfFileInt(void * hFile, const char *szSection, const char *szIdentifier, int iData);
315 
316 
317 
318 // XSETTINGS
319 
330 void CHSettingsRefresh(Display *pDisplay); // call this to re-read and re-build XSettings info
331 
332 // X11 settings collection
333 
338 {
342 };
343 
344 
369 typedef struct __XSETTINGS_DATA_COLOR__ // also used internally by XSettings
370 {
371  unsigned short sRed;
372  unsigned short sBlue;
373  unsigned short sGreen;
374  unsigned short sAlpha;
376 
377 
410 typedef struct _CHXSetting_
411 {
412  const char *szName;
413  int iType;
414  int iLen;
415  unsigned int uiSerial;
416  union
417  {
418  int iData;
420  XSETTINGS_DATA_COLOR clrData;
421  void *pData;
422  char *szData;
423  } uData;
425 
426 
452 typedef struct _CHXSettings_
453 {
454  Display *pDisplay;
455  int nSettings;
456  unsigned int uiSerial;
457  CHXSetting aData[1];
458 } CHXSettings;
459 
460 
470 const CHXSettings * CHGetXSettings(Display *pDisplay);
471 
483 const CHXSetting * CHGetXSetting(Display *pDisplay, const char *szSettingName);
484 
485 
496 int CHGetDoubleClickTime(Display *pDisplay);
497 
508 int CHGetDoubleClickDistance(Display *pDisplay);
509 
520 int CHGetDragThreshold(Display *pDisplay);
521 
532 int CHGetCursorBlink(Display *pDisplay);
533 
544 int CHGetCursorBlinkTime(Display *pDisplay);
545 
546 
547 
548 // XML help
549 
592 typedef struct _CHXMLEntry_
593 {
597 
600 
601 } CHXMLEntry;
602 
653 CHXMLEntry *CHParseXML(const char *pXMLData, int cbLength);
654 
664 void CHDebugDumpXML(CHXMLEntry *pEntry); // dumps XML using debug I/O functions
665 
680 char *CHParseXMLTagContents(const char *pTagContents, int cbLength);
681 
715 const char *CHFindNextXMLTag(const char *pTagContents, int cbLength, int nNestingFlags);
716 
739 const char *CHFindEndOfXMLTag(const char *pTagContents, int cbLength);
740 
741 
768 const char *CHFindEndOfXMLSection(const char *pTagContents, int cbLength, char cEndChar, int bUseQuotes);
769 
770 
771 // MIME type help
772 
784 char *CHGetFileMimeType(const char *szFileName);
785 
800 char *CHGetMimeDefaultApp(const char *szMimeType);
801 
814 char *CHGetDesktopFileInfo(const char *szDesktopFile, const char *szInfo);
815 
816 
817 
818 // debug
819 #ifndef NO_DEBUG
820 
828 void CHDumpConfig(void);
829 
830 #endif // NO_DEBUG
831 
832 #ifdef __cplusplus
833 };
834 #endif // __cplusplus
835 
836 
837 #endif // CONF_HELPER_H_INCLUDED
838 
char * CHGetMimeDefaultApp(const char *szMimeType)
Get the default application for a particular MIME type.
Definition: conf_help.c:3056
const CHXSettings * CHGetXSettings(Display *pDisplay)
returns a pointer to the cached X settings
int CHGetDoubleClickDistance(Display *pDisplay)
returns default double click distance (from X settings)
Definition: conf_help.c:2186
int nSettings
the total number of settings in aData
Definition: conf_help.h:455
unsigned int uiSerial
serial # from last XSETTINGS [endian-ized]
Definition: conf_help.h:415
int iData
The data as an integer value.
Definition: conf_help.h:418
unsigned short sRed
16-bit RGB value for RED
Definition: conf_help.h:371
const CHXSetting * CHGetXSetting(Display *pDisplay, const char *szSettingName)
returns a pointer to a specific X setting entry by name
Definition: conf_help.c:1727
void CHOnExit(void)
frees resources used by Configuration 'helper' functions
Definition: conf_help.c:166
int nLabelOffset
BYTE offset to label (zero-byte-terminated) string (from beginning of array) for this entry; <= 0 for...
Definition: conf_help.h:598
#define __PACKED__
PACKED definition.
const char * CHFindEndOfXMLTag(const char *pTagContents, int cbLength)
Parses contents of an XML tag to find the end of it.
Definition: conf_help.c:3023
int iType
The setting type (XSettingsType enumeration)
Definition: conf_help.h:413
unsigned short sAlpha
16-bit ALPHA value. If not used, it will be 0xffff
Definition: conf_help.h:374
struct __XSETTINGS_DATA_COLOR__ XSETTINGS_DATA_COLOR
Structure for storing configuration color information, XSettingsTypeColor.
void * CHOpenConfFile(const char *szAppName, int iFlags)
open configuration file for read/write, optionally creating it, based on application name ...
Definition: conf_help.c:637
const char * CHFindEndOfXMLSection(const char *pTagContents, int cbLength, char cEndChar, int bUseQuotes)
Parses XML text for the end of a &#39;section&#39;, typically ending in &#39;>&#39; &#39;)&#39; or &#39;]&#39;.
Definition: conf_help.c:2887
int CHGetConfFileString(void *hFile, const char *szSection, const char *szIdentifier, char *szData, int cbData)
obtain a string from a configuration file
Definition: conf_help.c:1223
int CHGetCursorBlinkTime(Display *pDisplay)
returns default cursor blink time (from X settings)
Definition: conf_help.c:2303
const char * CHFindNextXMLTag(const char *pTagContents, int cbLength, int nNestingFlags)
Parses contents of a XML to find the next tag, skipping comments along the way.
Definition: conf_help.c:2835
int nDataOffset
BYTE offset to data (zero-byte-terminated) string (from beginning of array) for the entry data; <= 0 ...
Definition: conf_help.h:599
int CHGetArgC(void)
retrieves the argument count stored by CHRegisterArgs()
Definition: conf_help.c:624
struct _CHXSettings_ CHXSettings
Array wrapper for CHXSetting cache.
unsigned int uiSerial
serial number from last XSETTINGS query
Definition: conf_help.h:456
Array wrapper for CHXSetting cache.
Definition: conf_help.h:452
void * pData
un-typed pointer to data within string area
Definition: conf_help.h:421
int CHGetResourceString(Display *pDisplay, const char *szIdentifier, char *szData, int cbData)
Queries desktop resource strings (may become deprecated)
Definition: conf_help.c:474
int CHWriteConfFileString(void *hFile, const char *szSection, const char *szIdentifier, const char *szData)
write a string to a configuration file
Definition: conf_help.c:1357
const char * szName
pointer to the NAME string within memory that follows CHXSettings::aData
Definition: conf_help.h:412
void CHCloseConfFile(void *hFile)
close configuration file opened by CHOpenConfFile(), but does NOT free memory resources ...
Definition: conf_help.c:831
unsigned short sGreen
16-bit RGB value for Green
Definition: conf_help.h:373
WB_INT64 llData
Reserved element, forces 64-bit size.
Definition: conf_help.h:419
int CHGetResourceInt(Display *pDisplay, const char *szIdentifier)
Queryies desktop resource integer values (from strings) (may become deprecated)
Definition: conf_help.c:598
int iContainer
0-based index for container; <= 0 for none.
Definition: conf_help.h:595
CHXMLEntry * CHParseXML(const char *pXMLData, int cbLength)
Parses contents of an XML tag, returning as WBAlloc&#39;d string list similar to environment strings...
Definition: conf_help.c:2410
void CHDumpConfig(void)
dump config information using debug output functions
Definition: conf_help.c:3192
Structure for storing settings information internally.
Definition: conf_help.h:410
Structure for storing configuration color information, XSettingsTypeColor.
Definition: conf_help.h:369
int iContentsIndex
0-based first array index for &#39;contents&#39; for this entry; <= 0 for none
Definition: conf_help.h:596
unsigned short sBlue
16-bit RGB value for Blue
Definition: conf_help.h:372
int CHGetDoubleClickTime(Display *pDisplay)
returns default double click time (from X settings)
Definition: conf_help.c:2147
int iLen
length (where applicable)
Definition: conf_help.h:414
The setting is an RGBA Color stored as XSETTINGS_DATA_COLOR.
Definition: conf_help.h:341
int CHGetCursorBlink(Display *pDisplay)
returns default cursor blink &#39;enable&#39; flag (from X settings)
Definition: conf_help.c:2264
int CHWriteConfFileInt(void *hFile, const char *szSection, const char *szIdentifier, int iData)
write an integer value to a configuration file
Definition: conf_help.c:1643
void CHSettingsRefresh(Display *pDisplay)
refresh the internally cached X settings
Definition: conf_help.c:1749
int CHGetConfFileInt(void *hFile, const char *szSection, const char *szIdentifier)
obtain an integer value from a configuration file
Definition: conf_help.c:1621
XSETTINGS_DATA_COLOR clrData
The data as a color value.
Definition: conf_help.h:420
char * CHGetFileMimeType(const char *szFileName)
Get the MIME type for a particular file name or extension.
Definition: conf_help.c:3034
The setting is an integer.
Definition: conf_help.h:339
char * szData
&#39;char&#39; typed pointer to data within string area
Definition: conf_help.h:422
Display * pDisplay
identifies which display it belongs to (reserved)
Definition: conf_help.h:454
int CHGetDragThreshold(Display *pDisplay)
returns default drag threshold (from X settings)
Definition: conf_help.c:2225
const char *const * CHGetArgV(void)
retrieves the array of arguments stored by CHRegisterArgs()
Definition: conf_help.c:629
void CHDebugDumpXML(CHXMLEntry *pEntry)
Parses contents of an XML tag, returning as WBAlloc&#39;d string list similar to environment strings...
long long WB_INT64
Platform abstract 64-bit integer.
Definition file for platform-specific utility functions.
void CHDestroyConfFile(void *hFile)
destroy configuration file opened by CHOpenConfFile(), freeing memory resources (but not the files) ...
Definition: conf_help.c:863
The setting is a 0-byte terminated ASCII string.
Definition: conf_help.h:340
struct _CHXMLEntry_ CHXMLEntry
Descriptor for parsed XML entry.
char * CHGetDesktopFileInfo(const char *szDesktopFile, const char *szInfo)
Get the default application for a particular MIME type.
Definition: conf_help.c:3087
int iNextIndex
0-based index for next item at this level; <= 0 for none. 0 marks "end of list" for top level ...
Definition: conf_help.h:594
XSettingsType
Enumeration for &#39;XSettingsType&#39; which describes the type of setting being cached. ...
Definition: conf_help.h:337
struct _CHXSetting_ CHXSetting
Structure for storing settings information internally.
char * CHParseXMLTagContents(const char *pTagContents, int cbLength)
Parses contents of a single XML tag, returning as WBAlloc&#39;d string list similar to environment string...
Definition: conf_help.c:2546
Descriptor for parsed XML entry.
Definition: conf_help.h:592