home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / x11r6.1 / man / cat3 / xrmqgetresource.0 < prev    next >
Encoding:
C/C++ Source or Header  |  1996-10-17  |  9.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. XrmGetResource(3X11)      XLIB FUNCTIONS     XrmGetResource(3X11)
  5.  
  6.  
  7. NNAAMMEE
  8.        XrmGetResource, XrmQGetResource, XrmQGetSearchList,
  9.        XrmQGetSearchResource - retrieve database resources and
  10.        search lists
  11.  
  12. SSYYNNTTAAXX
  13.        Bool XrmGetResource(_d_a_t_a_b_a_s_e, _s_t_r___n_a_m_e, _s_t_r___c_l_a_s_s,
  14.        _s_t_r___t_y_p_e___r_e_t_u_r_n, _v_a_l_u_e___r_e_t_u_r_n)
  15.         XrmDatabase _d_a_t_a_b_a_s_e;
  16.         char *_s_t_r___n_a_m_e;
  17.         char *_s_t_r___c_l_a_s_s;
  18.         char **_s_t_r___t_y_p_e___r_e_t_u_r_n;
  19.         XrmValue *_v_a_l_u_e___r_e_t_u_r_n;
  20.  
  21.        Bool XrmQGetResource(_d_a_t_a_b_a_s_e, _q_u_a_r_k___n_a_m_e, _q_u_a_r_k___c_l_a_s_s,
  22.        _q_u_a_r_k___t_y_p_e___r_e_t_u_r_n, _v_a_l_u_e___r_e_t_u_r_n)
  23.         XrmDatabase _d_a_t_a_b_a_s_e;
  24.         XrmNameList _q_u_a_r_k___n_a_m_e;
  25.         XrmClassList _q_u_a_r_k___c_l_a_s_s;
  26.         XrmRepresentation *_q_u_a_r_k___t_y_p_e___r_e_t_u_r_n;
  27.         XrmValue *_v_a_l_u_e___r_e_t_u_r_n;
  28.  
  29.        typedef XrmHashTable *XrmSearchList;
  30.  
  31.        Bool XrmQGetSearchList(_d_a_t_a_b_a_s_e, _n_a_m_e_s, _c_l_a_s_s_e_s,
  32.        _l_i_s_t___r_e_t_u_r_n, _l_i_s_t___l_e_n_g_t_h)
  33.         XrmDatabase _d_a_t_a_b_a_s_e;
  34.         XrmNameList _n_a_m_e_s;
  35.         XrmClassList _c_l_a_s_s_e_s;
  36.         XrmSearchList _l_i_s_t___r_e_t_u_r_n;
  37.         int _l_i_s_t___l_e_n_g_t_h;
  38.  
  39.        Bool XrmQGetSearchResource(_l_i_s_t, _n_a_m_e, _c_l_a_s_s, _t_y_p_e___r_e_t_u_r_n,
  40.        _v_a_l_u_e___r_e_t_u_r_n)
  41.         XrmSearchList _l_i_s_t;
  42.         XrmName _n_a_m_e;
  43.         XrmClass _c_l_a_s_s;
  44.         XrmRepresentation *_t_y_p_e___r_e_t_u_r_n;
  45.         XrmValue *_v_a_l_u_e___r_e_t_u_r_n;
  46.  
  47. AARRGGUUMMEENNTTSS
  48.        _c_l_a_s_s     Specifies the resource class.
  49.  
  50.        _c_l_a_s_s_e_s     Specifies a list of resource classes.
  51.  
  52.        _d_a_t_a_b_a_s_e     Specifies the database that is to be used.
  53.  
  54.        _l_i_s_t     Specifies the search list returned by
  55.          _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.
  56.  
  57.        _l_i_s_t___l_e_n_g_t_h
  58.          Specifies the number of entries (not the byte
  59.          size) allocated for list_return.
  60.  
  61.  
  62.  
  63.  
  64. X Version 11           Release 6.1                1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. XrmGetResource(3X11)      XLIB FUNCTIONS     XrmGetResource(3X11)
  71.  
  72.  
  73.        _l_i_s_t___r_e_t_u_r_n
  74.          Returns a search list for further use.
  75.  
  76.        _n_a_m_e     Specifies the resource name.
  77.  
  78.        _n_a_m_e_s     Specifies a list of resource names.
  79.  
  80.        _q_u_a_r_k___c_l_a_s_s
  81.          Specifies the fully qualified class of the value
  82.          being retrieved (as a quark).
  83.  
  84.        _q_u_a_r_k___n_a_m_e
  85.          Specifies the fully qualified name of the value
  86.          being retrieved (as a quark).
  87.  
  88.        _q_u_a_r_k___t_y_p_e___r_e_t_u_r_n
  89.          Returns the representation type of the destina-
  90.          tion (as a quark).
  91.  
  92.        _s_t_r___c_l_a_s_s Specifies the fully qualified class of the value
  93.          being retrieved (as a string).
  94.  
  95.        _s_t_r___n_a_m_e     Specifies the fully qualified name of the value
  96.          being retrieved (as a string).
  97.  
  98.        _s_t_r___t_y_p_e___r_e_t_u_r_n
  99.          Returns the representation type of the destina-
  100.          tion (as a string).
  101.  
  102.        _t_y_p_e___r_e_t_u_r_n
  103.          Returns data representation type.
  104.  
  105.        _v_a_l_u_e___r_e_t_u_r_n
  106.          Returns the value in the database.
  107.  
  108. DDEESSCCRRIIPPTTIIOONN
  109.        The _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e functions retrieve
  110.        a resource from the specified database.    Both take a fully
  111.        qualified name/class pair, a destination resource repre-
  112.        sentation, and the address of a value (size/address pair).
  113.        The value and returned type point into database memory;
  114.        therefore, you must not modify the data.
  115.  
  116.        The database only frees or overwrites entries on
  117.        _X_r_m_P_u_t_R_e_s_o_u_r_c_e, _X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e, or _X_r_m_M_e_r_g_e_D_a_t_a_b_a_s_e_s.  A
  118.        client that is not storing new values into the database or
  119.        is not merging the database should be safe using the
  120.        address passed back at any time until it exits.    If a
  121.        resource was found, both _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_-
  122.        _s_o_u_r_c_e return _T_r_u_e; otherwise, they return _F_a_l_s_e.
  123.  
  124.        The _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t function takes a list of names and
  125.        classes and returns a list of database levels where a
  126.        match might occur.  The returned list is in best-to-worst
  127.  
  128.  
  129.  
  130. X Version 11           Release 6.1                2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. XrmGetResource(3X11)      XLIB FUNCTIONS     XrmGetResource(3X11)
  137.  
  138.  
  139.        order and uses the same algorithm as _X_r_m_G_e_t_R_e_s_o_u_r_c_e for
  140.        determining precedence.    If list_return was large enough
  141.        for the search list, _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t returns _T_r_u_e; oth-
  142.        erwise, it returns _F_a_l_s_e.
  143.  
  144.        The size of the search list that the caller must allocate
  145.        is dependent upon the number of levels and wildcards in
  146.        the resource specifiers that are stored in the database.
  147.        The worst case length is %3 sup n%, where _n is the number
  148.        of name or class components in names or classes.
  149.  
  150.        When using _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t followed by multiple probes
  151.        for resources with a common name and class prefix, only
  152.        the common prefix should be specified in the name and
  153.        class list to _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.
  154.  
  155.        The _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e function searches the specified
  156.        database levels for the resource that is fully identified
  157.        by the specified name and class.     The search stops with
  158.        the first match.     _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e returns _T_r_u_e if
  159.        the resource was found; otherwise, it returns _F_a_l_s_e.
  160.  
  161.        A call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t with a name and class list
  162.        containing all but the last component of a resource name
  163.        followed by a call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e with the last
  164.        component name and class returns the same database entry
  165.        as _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e with the fully qual-
  166.        ified name and class.
  167.  
  168. MMAATTCCHHIINNGG RRUULLEESS
  169.        The algorithm for determining which resource database
  170.        entry matches a given query is the heart of the resource
  171.        manager.     All queries must fully specify the name and
  172.        class of the desired resource (use of the characters ``*''
  173.        and ``?'' are not permitted).  The library supports up to
  174.        100 components in a full name or class.    Resources are
  175.        stored in the database with only partially specified names
  176.        and classes, using pattern matching constructs.    An aster-
  177.        isk (*) is a loose binding and is used to represent any
  178.        number of intervening components, including none.  A
  179.        period (.) is a tight binding and is used to separate
  180.        immediately adjacent components.     A question mark (?) is
  181.        used to match any single component name or class.  A
  182.        database entry cannot end in a loose binding; the final
  183.        component (which cannot be the character ``?'') must be
  184.        specified.  The lookup algorithm searches the database for
  185.        the entry that most closely matches (is most specific for)
  186.        the full name and class being queried.  When more than one
  187.        database entry matches the full name and class, precedence
  188.        rules are used to select just one.
  189.  
  190.        The full name and class are scanned from left to right
  191.        (from highest level in the hierarchy to lowest), one com-
  192.        ponent at a time.  At each level, the corresponding
  193.  
  194.  
  195.  
  196. X Version 11           Release 6.1                3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. XrmGetResource(3X11)      XLIB FUNCTIONS     XrmGetResource(3X11)
  203.  
  204.  
  205.        component and/or binding of each matching entry is deter-
  206.        mined, and these matching components and bindings are com-
  207.        pared according to precedence rules.  Each of the rules is
  208.        applied at each level before moving to the next level,
  209.        until a rule selects a single entry over all others.  The
  210.        rules, in order of precedence, are:
  211.  
  212.        1.   An entry that contains a matching component (whether
  213.         name, class, or the character ``?'')  takes prece-
  214.         dence over entries that elide the level (that is,
  215.         entries that match the level in a loose binding).
  216.  
  217.        2.   An entry with a matching name takes precedence over
  218.         both entries with a matching class and entries that
  219.         match using the character ``?''.  An entry with a
  220.         matching class takes precedence over entries that
  221.         match using the character ``?''.
  222.  
  223.        3.   An entry preceded by a tight binding takes precedence
  224.         over entries preceded by a loose binding.
  225.  
  226. SSEEEE AALLSSOO
  227.        XrmInitialize(3X11), XrmMergeDatabases(3X11), XrmPutRe-
  228.        source(3X11), XrmUniqueQuark(3X11)
  229.        _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262. X Version 11           Release 6.1                4
  263.  
  264.  
  265.