Added the new TypeEx property and fixed Type

The Type property is now almost consistent with the MediaServer2Spec Type
property.  This should remove a source of constant confusion and
fix a number of bugs, in for example the download sync controller.
dLeyna-server's implementation of Type differs only from MediaServer2Spec
in one way.  dLeyna-server has introduced one new value, item.unclassified,
which is used when the object in question is an item but not one of the
items supported by MediaServer2Spec, i.e., not an audio, video or image
item.

A new property, TypeEx has been introduced.  TypeEx contains the
extended type information for an object, i.e., the value Type used
to hold (althought the values have changed), so if applications want
the extended type they can still retrieve it.

Both Type and TypeEx are searchable.  The superset of values specified
by TypeEx are permitted when creating a container, both in the type
of the container and it its create classes.

The extended type is exposed in the CreateClasses of a container and in
the LastChange event.

Type is no longer permitted in Update.  TypeEx must be used.

From an API point of view there are two breakagaes:

1. Applications that used Type to retrieve extended type information,
   need to be updated to use TypeEx.  Applications that used Type
   in their search queries might also need to be updated.
2. Applications that updated the Type of an object will need to be
   updated to use TypeEx instead.

There is one slightly unpleasent hack required to report the correct
values for Search and Sort Caps.  A correct solution would require
making the p_map hash table many to many, which would result in a bigger
change.  I've left this improvement for another commit.

Signed-off-by: Mark Ryan <mark.d.ryan@intel.com>

1 files changed, 71 insertions, 26 deletions

diff --git a/doc/server/dbus/API.txt b/doc/server/dbus/API.txt
index dfb05ed..3f121b1 100644
--- a/doc/server/dbus/API.txt
+++ b/doc/server/dbus/API.txt
@@ -262,13 +262,13 @@ not necessarily finished.  There are two return values.  The UploadId,
 which can be used to monitor the progress of the upload and to
 cancel it and ObjectPath, which contains the path of the newly created object.
 
-CreateContainerInAnyContainer(s DisplayName, s Type, as ChildTypes)
+CreateContainerInAnyContainer(s DisplayName, s TypeEx, as ChildTypes)
                                                              -> o ObjectPath
 
 Creates a new container. The DMS chooses the best place to create
 this new container. DisplayName is the name of the new container,
-Type is the type and ChildTypes is an array of types that can be stored
-in the new folder, e.g., ['video','container'].
+TypeEx is the extended type and ChildTypes is an array of extended types that
+can be stored in the new folder, e.g., ['video','container'].
 A special value of ['*'] indicates that no restriction is placed
 on the types of objects that can be stored in the container.
 The path of the newly created object is returned.
@@ -361,7 +361,7 @@ The value of each dictionary entry depends on the key value.
 | o | M | Contains the Object Path property of the parent container to which   |
 |   |   | this object was added.                                               |
 |------------------------------------------------------------------------------|
-| s | M | Contains the value of the Type (converted upnp:class property)       |
+| s | M | Contains the value of the TypeEx (converted upnp:class property)     |
 |   |   | of the object that was added.                                        |
 |------------------------------------------------------------------------------|
 
@@ -446,18 +446,33 @@ additional values for the Type property.
 Additional Values for the Type Property:
 ----------------------------------------
 
-The Type property tells what kind of object we are dealing with and
-which can take the below values in addition to those described
-in MediaServer2Spec specification (3).
-in case of Items:
- 'video.musicclip', 'video.broadcast'
- 'audio.broadcast', 'audio.book',
- 'item.playlist', 'item'
-and in case of Containers:
- 'album', 'album.music', 'album.photo'
- 'person', 'person.musicartist'
- 'genre', 'genre.music', 'genre.movie'
- 'playlist', 'storage'
+The MediaServer2Spec type property can be set to one of only seven
+possible values:  'container', 'video', 'video.movie', 'audio',
+'music', 'image' or 'image.photo'.  This causes a number of problems
+for dLeyna-server.  First, there is only one value for container, so
+it is not possible to indicate if the container is an album or a
+playlist, for instance.  Secondly, there is no way to represent an item
+that is not an audio, video or image item, such as a generic item
+(UPnP class of object.item) or a playlist item.
+
+dLeyna-server solves these two different problems in two ways:
+
+- It provides a new property called TypeEx, which provides extended
+  type information.  TypeEx is a superset of Type, providing specific
+  values of object types that are not supported by Type.  For example,
+  for an album, Type will be container but TypeEx will be set to
+  container.album.musicAlbum.
+
+- It provides a new catch all value for Type, item.unclassified.
+  item.unclassified means that the object is an item but it is not
+  an audio, video, or image item, e.g.,a  generic item or a playlist item.
+  The actual type of the item is stored in TypeEx.  item.unclassified
+  may be specified as a value for the Type property in searches.  In such
+  cases it is treated as the UPnP type object.item.
+
+Adding an additional value to MediaServer2Spec's Type property breaks our
+compliance with this spec a little, but it is necessary to achieve UPnP
+certification. 
 
 Additional Properties:
 ----------------------
@@ -482,6 +497,25 @@ Additional Properties:
 |                 |       |      |  for the object relative to the          |
 |                 |       |      |  SystemUpdateID state variable.          |
 |---------------------------------------------------------------------------|
+| TypeEx          |  s    |  m   |  The extended Type of the object.        |
+|                 |       |      |  TypeEx permits a superset of the values |
+|                 |       |      |  supported by the Type property.  When   |
+|                 |       |      |  the Type of an object is accurately     |
+|                 |       |      |  described by Type, i.e., the object     |
+|                 |       |      |  is a basic container or is an image,    |
+|                 |       |      |  audio, or video file, TypeEx = Type.    |
+|                 |       |      |  For objects where this is not the case, |
+|                 |       |      |  e.g., an album, the TypeEx value is     |
+|                 |       |      |  formed by removing the                  |
+|                 |       |      |  "object."  the prefix from the upnp     |
+|                 |       |      |  class. For example, the TypeEx value    |
+|                 |       |      |  for the upnp class,                     |
+|                 |       |      |  object.container.playlistContainer is   |
+|                 |       |      |  container.playlistContainer.            |
+|                 |       |      |                                          |
+|                 |       |      |  Since version 0.2.0.                    |
+|---------------------------------------------------------------------------|
+
 
 
 Additional Methods:
@@ -502,7 +536,7 @@ property name value pairs that are to be updated, or added if they do
 not already exist.  ToDelete is an array of properties to be deleted.
 The same property cannot appear in both ToAddUpdate and ToDelete.
 Only the following properties can be updated: 'Date', 'DisplayName',
-'Artists', 'Album', 'Type', 'TrackNumber'.
+'Artists', 'Album', 'TypeEx', 'TrackNumber'.
 
 GetMetaData() -> s
 
@@ -548,12 +582,23 @@ Additional properties unsupported by org.gnome.MediaContainer2
 |---------------------------------------------------------------------------|
 |     Name               | Type | m/o* |              Description           |
 |---------------------------------------------------------------------------|
-| CreateClasses          |a(sb) |  o   |  Array of UPnP createClasses       |
-|                        |      |      |  property. A createClasses         |
-|                        |      |      |  property is a tuple (sb)          |
-|                        |      |      |  representing the class and        |
-|                        |      |      |  whether derived values are        |
-|                        |      |      |  allowed for this class.           |
+| CreateClasses          |a(sb) |  o   |  The CreateClasses property is an  |      
+|                        |      |      |  array of tuples (sb) that lists   |
+|                        |      |      |  the extended types of objects that|
+|                        |      |      |  that can be created in a          |
+|                        |      |      |  container. A boolean value is     |
+|                        |      |      |  associated with each type.  This  |
+|                        |      |      |  boolean indicates whether objects |
+|                        |      |      |  of types derived from the         |
+|                        |      |      |  specified extended type can also  |
+|                        |      |      |  be created in this container.     |
+|                        |      |      |  For example,                      |
+|                        |      |      |  ("container.album.","true")       |
+|                        |      |      |  would indicate that objects of    |
+|                        |      |      |  type container.album,             |
+|                        |      |      |  container.album.music and         |
+|			 |	|      |  container.album.photo can be      |
+|                        |      |      |  created in the container.         |
 |---------------------------------------------------------------------------|
 | ContainerUpdateID      |  u   |  o   |  Contains the value of the         |
 |                        |      |      |  SystemUpdateID state variable     |
@@ -607,7 +652,7 @@ SearchObjectsEx(s Query, u Offset, u Max, as Filter, s SortBy) -> aa{sv}
 
 Upload(s DisplayName, s FilePath) -> (u UploadId, o ObjectPath)
 
-CreateContainer(s DisplayName, s Type, as ChildTypes) -> o ObjectPath
+CreateContainer(s DisplayName, s TypeEx, as ChildTypes) -> o ObjectPath
 
 CreateReference(o ObjectPath) -> o ObjectPath
 
@@ -676,8 +721,8 @@ suitable location for the file.
 
 The CreateContainer method creates a new child container.
 DisplayName is the name of the new container,
-Type is the type and ChildTypes is an array of types that can be stored
-in the new folder, e.g., ['video','container'].
+TypeEx is the extended type and ChildTypes is an array of extended 
+types that can be stored in the new folder, e.g., ['video','container'].
 A special value of ['*'] indicates that no restriction is placed
 on the types of objects that can be stored in the container.
 The path of the newly created object is returned.