qobject/qdict.c

   1 /*
   2  * QDict Module
   3  *
   4  * Copyright (C) 2009 Red Hat Inc.
   5  *
   6  * Authors:
   7  *  Luiz Capitulino <[email protected]>
   8  *
   9  * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
  10  * See the COPYING.LIB file in the top-level directory.
  11  */
  12
  13 #include "qapi/qmp/qint.h"
  14 #include "qapi/qmp/qfloat.h"
  15 #include "qapi/qmp/qdict.h"
  16 #include "qapi/qmp/qbool.h"
  17 #include "qapi/qmp/qstring.h"
  18 #include "qapi/qmp/qobject.h"
  19 #include "qemu/queue.h"
  20 #include "qemu-common.h"
  21
  22 static void qdict_destroy_obj(QObject *obj);
  23
  24 static const QType qdict_type = {
  25     .code = QTYPE_QDICT,
  26     .destroy = qdict_destroy_obj,
  27 };
  28
  29 /**
  30  * qdict_new(): Create a new QDict
  31  *
  32  * Return strong reference.
  33  */
  34 QDict *qdict_new(void)
  35 {
  36     QDict *qdict;
  37
  38     qdict = g_malloc0(sizeof(*qdict));
  39     QOBJECT_INIT(qdict, &qdict_type);
  40
  41     return qdict;
  42 }
  43
  44 /**
  45  * qobject_to_qdict(): Convert a QObject into a QDict
  46  */
  47 QDict *qobject_to_qdict(const QObject *obj)
  48 {
  49     if (!obj || qobject_type(obj) != QTYPE_QDICT) {
  50         return NULL;
  51     }
  52     return container_of(obj, QDict, base);
  53 }
  54
  55 /**
  56  * tdb_hash(): based on the hash agorithm from gdbm, via tdb
  57  * (from module-init-tools)
  58  */
  59 static unsigned int tdb_hash(const char *name)
  60 {
  61     unsigned value;     /* Used to compute the hash value.  */
  62     unsigned   i;       /* Used to cycle through random values. */
  63
  64     /* Set the initial value from the key size. */
  65     for (value = 0x238F13AF * strlen(name), i=0; name[i]; i++)
  66         value = (value + (((const unsigned char *)name)[i] << (i*5 % 24)));
  67
  68     return (1103515243 * value + 12345);
  69 }
  70
  71 /**
  72  * alloc_entry(): allocate a new QDictEntry
  73  */
  74 static QDictEntry *alloc_entry(const char *key, QObject *value)
  75 {
  76     QDictEntry *entry;
  77
  78     entry = g_malloc0(sizeof(*entry));
  79     entry->key = g_strdup(key);
  80     entry->value = value;
  81
  82     return entry;
  83 }
  84
  85 /**
  86  * qdict_entry_value(): Return qdict entry value
  87  *
  88  * Return weak reference.
  89  */
  90 QObject *qdict_entry_value(const QDictEntry *entry)
  91 {
  92     return entry->value;
  93 }
  94
  95 /**
  96  * qdict_entry_key(): Return qdict entry key
  97  *
  98  * Return a *pointer* to the string, it has to be duplicated before being
  99  * stored.
 100  */
 101 const char *qdict_entry_key(const QDictEntry *entry)
 102 {
 103     return entry->key;
 104 }
 105
 106 /**
 107  * qdict_find(): List lookup function
 108  */
 109 static QDictEntry *qdict_find(const QDict *qdict,
 110                               const char *key, unsigned int bucket)
 111 {
 112     QDictEntry *entry;
 113
 114     QLIST_FOREACH(entry, &qdict->table[bucket], next)
 115         if (!strcmp(entry->key, key))
 116             return entry;
 117
 118     return NULL;
 119 }
 120
 121 /**
 122  * qdict_put_obj(): Put a new QObject into the dictionary
 123  *
 124  * Insert the pair 'key:value' into 'qdict', if 'key' already exists
 125  * its 'value' will be replaced.
 126  *
 127  * This is done by freeing the reference to the stored QObject and
 128  * storing the new one in the same entry.
 129  *
 130  * NOTE: ownership of 'value' is transferred to the QDict
 131  */
 132 void qdict_put_obj(QDict *qdict, const char *key, QObject *value)
 133 {
 134     unsigned int bucket;
 135     QDictEntry *entry;
 136
 137     bucket = tdb_hash(key) % QDICT_BUCKET_MAX;
 138     entry = qdict_find(qdict, key, bucket);
 139     if (entry) {
 140         /* replace key's value */
 141         qobject_decref(entry->value);
 142         entry->value = value;
 143     } else {
 144         /* allocate a new entry */
 145         entry = alloc_entry(key, value);
 146         QLIST_INSERT_HEAD(&qdict->table[bucket], entry, next);
 147         qdict->size++;
 148     }
 149 }
 150
 151 /**
 152  * qdict_get(): Lookup for a given 'key'
 153  *
 154  * Return a weak reference to the QObject associated with 'key' if
 155  * 'key' is present in the dictionary, NULL otherwise.
 156  */
 157 QObject *qdict_get(const QDict *qdict, const char *key)
 158 {
 159     QDictEntry *entry;
 160
 161     entry = qdict_find(qdict, key, tdb_hash(key) % QDICT_BUCKET_MAX);
 162     return (entry == NULL ? NULL : entry->value);
 163 }
 164
 165 /**
 166  * qdict_haskey(): Check if 'key' exists
 167  *
 168  * Return 1 if 'key' exists in the dict, 0 otherwise
 169  */
 170 int qdict_haskey(const QDict *qdict, const char *key)
 171 {
 172     unsigned int bucket = tdb_hash(key) % QDICT_BUCKET_MAX;
 173     return (qdict_find(qdict, key, bucket) == NULL ? 0 : 1);
 174 }
 175
 176 /**
 177  * qdict_size(): Return the size of the dictionary
 178  */
 179 size_t qdict_size(const QDict *qdict)
 180 {
 181     return qdict->size;
 182 }
 183
 184 /**
 185  * qdict_get_obj(): Get a QObject of a specific type
 186  */
 187 static QObject *qdict_get_obj(const QDict *qdict, const char *key,
 188                               qtype_code type)
 189 {
 190     QObject *obj;
 191
 192     obj = qdict_get(qdict, key);
 193     assert(obj != NULL);
 194     assert(qobject_type(obj) == type);
 195
 196     return obj;
 197 }
 198
 199 /**
 200  * qdict_get_double(): Get an number mapped by 'key'
 201  *
 202  * This function assumes that 'key' exists and it stores a
 203  * QFloat or QInt object.
 204  *
 205  * Return number mapped by 'key'.
 206  */
 207 double qdict_get_double(const QDict *qdict, const char *key)
 208 {
 209     QObject *obj = qdict_get(qdict, key);
 210
 211     assert(obj);
 212     switch (qobject_type(obj)) {
 213     case QTYPE_QFLOAT:
 214         return qfloat_get_double(qobject_to_qfloat(obj));
 215     case QTYPE_QINT:
 216         return qint_get_int(qobject_to_qint(obj));
 217     default:
 218         abort();
 219     }
 220 }
 221
 222 /**
 223  * qdict_get_int(): Get an integer mapped by 'key'
 224  *
 225  * This function assumes that 'key' exists and it stores a
 226  * QInt object.
 227  *
 228  * Return integer mapped by 'key'.
 229  */
 230 int64_t qdict_get_int(const QDict *qdict, const char *key)
 231 {
 232     return qint_get_int(qobject_to_qint(qdict_get(qdict, key)));
 233 }
 234
 235 /**
 236  * qdict_get_bool(): Get a bool mapped by 'key'
 237  *
 238  * This function assumes that 'key' exists and it stores a
 239  * QBool object.
 240  *
 241  * Return bool mapped by 'key'.
 242  */
 243 bool qdict_get_bool(const QDict *qdict, const char *key)
 244 {
 245     return qbool_get_bool(qobject_to_qbool(qdict_get(qdict, key)));
 246 }
 247
 248 /**
 249  * qdict_get_qlist(): Get the QList mapped by 'key'
 250  *
 251  * This function assumes that 'key' exists and it stores a
 252  * QList object.
 253  *
 254  * Return QList mapped by 'key'.
 255  */
 256 QList *qdict_get_qlist(const QDict *qdict, const char *key)
 257 {
 258     return qobject_to_qlist(qdict_get_obj(qdict, key, QTYPE_QLIST));
 259 }
 260
 261 /**
 262  * qdict_get_qdict(): Get the QDict mapped by 'key'
 263  *
 264  * This function assumes that 'key' exists and it stores a
 265  * QDict object.
 266  *
 267  * Return QDict mapped by 'key'.
 268  */
 269 QDict *qdict_get_qdict(const QDict *qdict, const char *key)
 270 {
 271     return qobject_to_qdict(qdict_get(qdict, key));
 272 }
 273
 274 /**
 275  * qdict_get_str(): Get a pointer to the stored string mapped
 276  * by 'key'
 277  *
 278  * This function assumes that 'key' exists and it stores a
 279  * QString object.
 280  *
 281  * Return pointer to the string mapped by 'key'.
 282  */
 283 const char *qdict_get_str(const QDict *qdict, const char *key)
 284 {
 285     return qstring_get_str(qobject_to_qstring(qdict_get(qdict, key)));
 286 }
 287
 288 /**
 289  * qdict_get_try_int(): Try to get integer mapped by 'key'
 290  *
 291  * Return integer mapped by 'key', if it is not present in
 292  * the dictionary or if the stored object is not of QInt type
 293  * 'def_value' will be returned.
 294  */
 295 int64_t qdict_get_try_int(const QDict *qdict, const char *key,
 296                           int64_t def_value)
 297 {
 298     QInt *qint = qobject_to_qint(qdict_get(qdict, key));
 299
 300     return qint ? qint_get_int(qint) : def_value;
 301 }
 302
 303 /**
 304  * qdict_get_try_bool(): Try to get a bool mapped by 'key'
 305  *
 306  * Return bool mapped by 'key', if it is not present in the
 307  * dictionary or if the stored object is not of QBool type
 308  * 'def_value' will be returned.
 309  */
 310 bool qdict_get_try_bool(const QDict *qdict, const char *key, bool def_value)
 311 {
 312     QBool *qbool = qobject_to_qbool(qdict_get(qdict, key));
 313
 314     return qbool ? qbool_get_bool(qbool) : def_value;
 315 }
 316
 317 /**
 318  * qdict_get_try_str(): Try to get a pointer to the stored string
 319  * mapped by 'key'
 320  *
 321  * Return a pointer to the string mapped by 'key', if it is not present
 322  * in the dictionary or if the stored object is not of QString type
 323  * NULL will be returned.
 324  */
 325 const char *qdict_get_try_str(const QDict *qdict, const char *key)
 326 {
 327     QString *qstr = qobject_to_qstring(qdict_get(qdict, key));
 328
 329     return qstr ? qstring_get_str(qstr) : NULL;
 330 }
 331
 332 /**
 333  * qdict_iter(): Iterate over all the dictionary's stored values.
 334  *
 335  * This function allows the user to provide an iterator, which will be
 336  * called for each stored value in the dictionary.
 337  */
 338 void qdict_iter(const QDict *qdict,
 339                 void (*iter)(const char *key, QObject *obj, void *opaque),
 340                 void *opaque)
 341 {
 342     int i;
 343     QDictEntry *entry;
 344
 345     for (i = 0; i < QDICT_BUCKET_MAX; i++) {
 346         QLIST_FOREACH(entry, &qdict->table[i], next)
 347             iter(entry->key, entry->value, opaque);
 348     }
 349 }
 350
 351 static QDictEntry *qdict_next_entry(const QDict *qdict, int first_bucket)
 352 {
 353     int i;
 354
 355     for (i = first_bucket; i < QDICT_BUCKET_MAX; i++) {
 356         if (!QLIST_EMPTY(&qdict->table[i])) {
 357             return QLIST_FIRST(&qdict->table[i]);
 358         }
 359     }
 360
 361     return NULL;
 362 }
 363
 364 /**
 365  * qdict_first(): Return first qdict entry for iteration.
 366  */
 367 const QDictEntry *qdict_first(const QDict *qdict)
 368 {
 369     return qdict_next_entry(qdict, 0);
 370 }
 371
 372 /**
 373  * qdict_next(): Return next qdict entry in an iteration.
 374  */
 375 const QDictEntry *qdict_next(const QDict *qdict, const QDictEntry *entry)
 376 {
 377     QDictEntry *ret;
 378
 379     ret = QLIST_NEXT(entry, next);
 380     if (!ret) {
 381         unsigned int bucket = tdb_hash(entry->key) % QDICT_BUCKET_MAX;
 382         ret = qdict_next_entry(qdict, bucket + 1);
 383     }
 384
 385     return ret;
 386 }
 387
 388 /**
 389  * qdict_clone_shallow(): Clones a given QDict. Its entries are not copied, but
 390  * another reference is added.
 391  */
 392 QDict *qdict_clone_shallow(const QDict *src)
 393 {
 394     QDict *dest;
 395     QDictEntry *entry;
 396     int i;
 397
 398     dest = qdict_new();
 399
 400     for (i = 0; i < QDICT_BUCKET_MAX; i++) {
 401         QLIST_FOREACH(entry, &src->table[i], next) {
 402             qobject_incref(entry->value);
 403             qdict_put_obj(dest, entry->key, entry->value);
 404         }
 405     }
 406
 407     return dest;
 408 }
 409
 410 /**
 411  * qentry_destroy(): Free all the memory allocated by a QDictEntry
 412  */
 413 static void qentry_destroy(QDictEntry *e)
 414 {
 415     assert(e != NULL);
 416     assert(e->key != NULL);
 417     assert(e->value != NULL);
 418
 419     qobject_decref(e->value);
 420     g_free(e->key);
 421     g_free(e);
 422 }
 423
 424 /**
 425  * qdict_del(): Delete a 'key:value' pair from the dictionary
 426  *
 427  * This will destroy all data allocated by this entry.
 428  */
 429 void qdict_del(QDict *qdict, const char *key)
 430 {
 431     QDictEntry *entry;
 432
 433     entry = qdict_find(qdict, key, tdb_hash(key) % QDICT_BUCKET_MAX);
 434     if (entry) {
 435         QLIST_REMOVE(entry, next);
 436         qentry_destroy(entry);
 437         qdict->size--;
 438     }
 439 }
 440
 441 /**
 442  * qdict_destroy_obj(): Free all the memory allocated by a QDict
 443  */
 444 static void qdict_destroy_obj(QObject *obj)
 445 {
 446     int i;
 447     QDict *qdict;
 448
 449     assert(obj != NULL);
 450     qdict = qobject_to_qdict(obj);
 451
 452     for (i = 0; i < QDICT_BUCKET_MAX; i++) {
 453         QDictEntry *entry = QLIST_FIRST(&qdict->table[i]);
 454         while (entry) {
 455             QDictEntry *tmp = QLIST_NEXT(entry, next);
 456             QLIST_REMOVE(entry, next);
 457             qentry_destroy(entry);
 458             entry = tmp;
 459         }
 460     }
 461
 462     g_free(qdict);
 463 }
 464
 465 /**
 466  * qdict_copy_default(): If no entry mapped by 'key' exists in 'dst' yet, the
 467  * value of 'key' in 'src' is copied there (and the refcount increased
 468  * accordingly).
 469  */
 470 void qdict_copy_default(QDict *dst, QDict *src, const char *key)
 471 {
 472     QObject *val;
 473
 474     if (qdict_haskey(dst, key)) {
 475         return;
 476     }
 477
 478     val = qdict_get(src, key);
 479     if (val) {
 480         qobject_incref(val);
 481         qdict_put_obj(dst, key, val);
 482     }
 483 }
 484
 485 /**
 486  * qdict_set_default_str(): If no entry mapped by 'key' exists in 'dst' yet, a
 487  * new QString initialised by 'val' is put there.
 488  */
 489 void qdict_set_default_str(QDict *dst, const char *key, const char *val)
 490 {
 491     if (qdict_haskey(dst, key)) {
 492         return;
 493     }
 494
 495     qdict_put(dst, key, qstring_from_str(val));
 496 }
 497
 498 static void qdict_flatten_qdict(QDict *qdict, QDict *target,
 499                                 const char *prefix);
 500
 501 static void qdict_flatten_qlist(QList *qlist, QDict *target, const char *prefix)
 502 {
 503     QObject *value;
 504     const QListEntry *entry;
 505     char *new_key;
 506     int i;
 507
 508     /* This function is never called with prefix == NULL, i.e., it is always
 509      * called from within qdict_flatten_q(list|dict)(). Therefore, it does not
 510      * need to remove list entries during the iteration (the whole list will be
 511      * deleted eventually anyway from qdict_flatten_qdict()). */
 512     assert(prefix);
 513
 514     entry = qlist_first(qlist);
 515
 516     for (i = 0; entry; entry = qlist_next(entry), i++) {
 517         value = qlist_entry_obj(entry);
 518         new_key = g_strdup_printf("%s.%i", prefix, i);
 519
 520         if (qobject_type(value) == QTYPE_QDICT) {
 521             qdict_flatten_qdict(qobject_to_qdict(value), target, new_key);
 522         } else if (qobject_type(value) == QTYPE_QLIST) {
 523             qdict_flatten_qlist(qobject_to_qlist(value), target, new_key);
 524         } else {
 525             /* All other types are moved to the target unchanged. */
 526             qobject_incref(value);
 527             qdict_put_obj(target, new_key, value);
 528         }
 529
 530         g_free(new_key);
 531     }
 532 }
 533
 534 static void qdict_flatten_qdict(QDict *qdict, QDict *target, const char *prefix)
 535 {
 536     QObject *value;
 537     const QDictEntry *entry, *next;
 538     char *new_key;
 539     bool delete;
 540
 541     entry = qdict_first(qdict);
 542
 543     while (entry != NULL) {
 544
 545         next = qdict_next(qdict, entry);
 546         value = qdict_entry_value(entry);
 547         new_key = NULL;
 548         delete = false;
 549
 550         if (prefix) {
 551             new_key = g_strdup_printf("%s.%s", prefix, entry->key);
 552         }
 553
 554         if (qobject_type(value) == QTYPE_QDICT) {
 555             /* Entries of QDicts are processed recursively, the QDict object
 556              * itself disappears. */
 557             qdict_flatten_qdict(qobject_to_qdict(value), target,
 558                                 new_key ? new_key : entry->key);
 559             delete = true;
 560         } else if (qobject_type(value) == QTYPE_QLIST) {
 561             qdict_flatten_qlist(qobject_to_qlist(value), target,
 562                                 new_key ? new_key : entry->key);
 563             delete = true;
 564         } else if (prefix) {
 565             /* All other objects are moved to the target unchanged. */
 566             qobject_incref(value);
 567             qdict_put_obj(target, new_key, value);
 568             delete = true;
 569         }
 570
 571         g_free(new_key);
 572
 573         if (delete) {
 574             qdict_del(qdict, entry->key);
 575
 576             /* Restart loop after modifying the iterated QDict */
 577             entry = qdict_first(qdict);
 578             continue;
 579         }
 580
 581         entry = next;
 582     }
 583 }
 584
 585 /**
 586  * qdict_flatten(): For each nested QDict with key x, all fields with key y
 587  * are moved to this QDict and their key is renamed to "x.y". For each nested
 588  * QList with key x, the field at index y is moved to this QDict with the key
 589  * "x.y" (i.e., the reverse of what qdict_array_split() does).
 590  * This operation is applied recursively for nested QDicts and QLists.
 591  */
 592 void qdict_flatten(QDict *qdict)
 593 {
 594     qdict_flatten_qdict(qdict, qdict, NULL);
 595 }
 596
 597 /* extract all the src QDict entries starting by start into dst */
 598 void qdict_extract_subqdict(QDict *src, QDict **dst, const char *start)
 599
 600 {
 601     const QDictEntry *entry, *next;
 602     const char *p;
 603
 604     *dst = qdict_new();
 605     entry = qdict_first(src);
 606
 607     while (entry != NULL) {
 608         next = qdict_next(src, entry);
 609         if (strstart(entry->key, start, &p)) {
 610             qobject_incref(entry->value);
 611             qdict_put_obj(*dst, p, entry->value);
 612             qdict_del(src, entry->key);
 613         }
 614         entry = next;
 615     }
 616 }
 617
 618 static int qdict_count_prefixed_entries(const QDict *src, const char *start)
 619 {
 620     const QDictEntry *entry;
 621     int count = 0;
 622
 623     for (entry = qdict_first(src); entry; entry = qdict_next(src, entry)) {
 624         if (strstart(entry->key, start, NULL)) {
 625             if (count == INT_MAX) {
 626                 return -ERANGE;
 627             }
 628             count++;
 629         }
 630     }
 631
 632     return count;
 633 }
 634
 635 /**
 636  * qdict_array_split(): This function moves array-like elements of a QDict into
 637  * a new QList. Every entry in the original QDict with a key "%u" or one
 638  * prefixed "%u.", where %u designates an unsigned integer starting at 0 and
 639  * incrementally counting up, will be moved to a new QDict at index %u in the
 640  * output QList with the key prefix removed, if that prefix is "%u.". If the
 641  * whole key is just "%u", the whole QObject will be moved unchanged without
 642  * creating a new QDict. The function terminates when there is no entry in the
 643  * QDict with a prefix directly (incrementally) following the last one; it also
 644  * returns if there are both entries with "%u" and "%u." for the same index %u.
 645  * Example: {"0.a": 42, "0.b": 23, "1.x": 0, "4.y": 1, "o.o": 7, "2": 66}
 646  *      (or {"1.x": 0, "4.y": 1, "0.a": 42, "o.o": 7, "0.b": 23, "2": 66})
 647  *       => [{"a": 42, "b": 23}, {"x": 0}, 66]
 648  *      and {"4.y": 1, "o.o": 7} (remainder of the old QDict)
 649  */
 650 void qdict_array_split(QDict *src, QList **dst)
 651 {
 652     unsigned i;
 653
 654     *dst = qlist_new();
 655
 656     for (i = 0; i < UINT_MAX; i++) {
 657         QObject *subqobj;
 658         bool is_subqdict;
 659         QDict *subqdict;
 660         char indexstr[32], prefix[32];
 661         size_t snprintf_ret;
 662
 663         snprintf_ret = snprintf(indexstr, 32, "%u", i);
 664         assert(snprintf_ret < 32);
 665
 666         subqobj = qdict_get(src, indexstr);
 667
 668         snprintf_ret = snprintf(prefix, 32, "%u.", i);
 669         assert(snprintf_ret < 32);
 670
 671         /* Overflow is the same as positive non-zero results */
 672         is_subqdict = qdict_count_prefixed_entries(src, prefix);
 673
 674         // There may be either a single subordinate object (named "%u") or
 675         // multiple objects (each with a key prefixed "%u."), but not both.
 676         if (!subqobj == !is_subqdict) {
 677             break;
 678         }
 679
 680         if (is_subqdict) {
 681             qdict_extract_subqdict(src, &subqdict, prefix);
 682             assert(qdict_size(subqdict) > 0);
 683         } else {
 684             qobject_incref(subqobj);
 685             qdict_del(src, indexstr);
 686         }
 687
 688         qlist_append_obj(*dst, subqobj ?: QOBJECT(subqdict));
 689     }
 690 }
 691
 692 /**
 693  * qdict_array_entries(): Returns the number of direct array entries if the
 694  * sub-QDict of src specified by the prefix in subqdict (or src itself for
 695  * prefix == "") is valid as an array, i.e. the length of the created list if
 696  * the sub-QDict would become empty after calling qdict_array_split() on it. If
 697  * the array is not valid, -EINVAL is returned.
 698  */
 699 int qdict_array_entries(QDict *src, const char *subqdict)
 700 {
 701     const QDictEntry *entry;
 702     unsigned i;
 703     unsigned entries = 0;
 704     size_t subqdict_len = strlen(subqdict);
 705
 706     assert(!subqdict_len || subqdict[subqdict_len - 1] == '.');
 707
 708     /* qdict_array_split() loops until UINT_MAX, but as we want to return
 709      * negative errors, we only have a signed return value here. Any additional
 710      * entries will lead to -EINVAL. */
 711     for (i = 0; i < INT_MAX; i++) {
 712         QObject *subqobj;
 713         int subqdict_entries;
 714         size_t slen = 32 + subqdict_len;
 715         char indexstr[slen], prefix[slen];
 716         size_t snprintf_ret;
 717
 718         snprintf_ret = snprintf(indexstr, slen, "%s%u", subqdict, i);
 719         assert(snprintf_ret < slen);
 720
 721         subqobj = qdict_get(src, indexstr);
 722
 723         snprintf_ret = snprintf(prefix, slen, "%s%u.", subqdict, i);
 724         assert(snprintf_ret < slen);
 725
 726         subqdict_entries = qdict_count_prefixed_entries(src, prefix);
 727         if (subqdict_entries < 0) {
 728             return subqdict_entries;
 729         }
 730
 731         /* There may be either a single subordinate object (named "%u") or
 732          * multiple objects (each with a key prefixed "%u."), but not both. */
 733         if (subqobj && subqdict_entries) {
 734             return -EINVAL;
 735         } else if (!subqobj && !subqdict_entries) {
 736             break;
 737         }
 738
 739         entries += subqdict_entries ? subqdict_entries : 1;
 740     }
 741
 742     /* Consider everything handled that isn't part of the given sub-QDict */
 743     for (entry = qdict_first(src); entry; entry = qdict_next(src, entry)) {
 744         if (!strstart(qdict_entry_key(entry), subqdict, NULL)) {
 745             entries++;
 746         }
 747     }
 748
 749     /* Anything left in the sub-QDict that wasn't handled? */
 750     if (qdict_size(src) != entries) {
 751         return -EINVAL;
 752     }
 753
 754     return i;
 755 }
 756
 757 /**
 758  * qdict_join(): Absorb the src QDict into the dest QDict, that is, move all
 759  * elements from src to dest.
 760  *
 761  * If an element from src has a key already present in dest, it will not be
 762  * moved unless overwrite is true.
 763  *
 764  * If overwrite is true, the conflicting values in dest will be discarded and
 765  * replaced by the corresponding values from src.
 766  *
 767  * Therefore, with overwrite being true, the src QDict will always be empty when
 768  * this function returns. If overwrite is false, the src QDict will be empty
 769  * iff there were no conflicts.
 770  */
 771 void qdict_join(QDict *dest, QDict *src, bool overwrite)
 772 {
 773     const QDictEntry *entry, *next;
 774
 775     entry = qdict_first(src);
 776     while (entry) {
 777         next = qdict_next(src, entry);
 778
 779         if (overwrite || !qdict_haskey(dest, entry->key)) {
 780             qobject_incref(entry->value);
 781             qdict_put_obj(dest, entry->key, entry->value);
 782             qdict_del(src, entry->key);
 783         }
 784
 785         entry = next;
 786     }
 787 }