diff options
author | Krzesimir Nowak <krnowak@openismus.com> | 2012-10-25 11:43:28 +0200 |
---|---|---|
committer | Krzesimir Nowak <krnowak@openismus.com> | 2012-10-25 11:47:40 +0200 |
commit | 0d717f6e72f04909775a60fd6f1b2a0a208f1629 (patch) | |
tree | 2865364861b2a760a0eaf512c1a04113eed9ee73 | |
parent | 68a0fa0a7bb385d08285657d7dbb0b0731e6633c (diff) | |
download | gupnp-av-0d717f6e72f04909775a60fd6f1b2a0a208f1629.tar.gz |
Add a comment explaining a bit a process of applying fragments.
-rw-r--r-- | libgupnp-av/gupnp-didl-lite-object.c | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/libgupnp-av/gupnp-didl-lite-object.c b/libgupnp-av/gupnp-didl-lite-object.c index 59f2251..30533c5 100644 --- a/libgupnp-av/gupnp-didl-lite-object.c +++ b/libgupnp-av/gupnp-didl-lite-object.c @@ -2291,6 +2291,46 @@ gupnp_didl_lite_object_unset_artists (GUPnPDIDLLiteObject *object) g_object_notify (G_OBJECT (object), "artist"); } +/* GENERAL DOCS ABOUT FRAGMENT APPLYING. + * + * The function applying fragments takes two arrays of fragments. One + * array contains current fragments and another one contains new + * fragments. Both arrays have to be of equal length and have more + * then zero elements. Each of fragments in both arrays make a pair + * (i.e. first/second/third/... fragment in current array and + * first/second/third/... fragment in new array form a pair). Each + * fragment can have zero, one or more XML elements. + * + * For each fragment pair first we check if current fragment is indeed + * a part of this object's document. If it is then we check validity + * of new fragment for applying. If it is then we replace the current + * fragment with new fragment in object's document copy and validate + * the modified document against didl-lite schema. After all fragment + * pairs are processed we replace a part describing this object in + * original document with respective one in modified document. + * + * Checking if current fragment is a part of object's document is in + * essence checking for deep equality of document's node and this + * fragment (i.e. element name and properties have to be equal, same + * for children). + * + * Checking if new fragment is valid for applying is about checking + * whether element in new fragment is either a context (i.e. both + * current element and new element are deep equal) or element + * modification (i.e. changes attributes but element name is still the + * same). There may be a case when there are more elements in current + * fragment than in new fragment then those excessive elements are + * checked whether they can be really removed. The other case is when + * there are more elements in new fragments than in current fragment - + * in such situation we check if additions are valid. + * + * By checking validity of modification, removals or additions we mean + * that no read-only properties are changed. Additionaly, for + * removals, we check if required properties are not removed. + * + * This approach may fail in some more twisted cases. + */ + /** * gupnp_didl_lite_object_apply_fragments: * @object: The #GUPnPDIDLLiteObject |