= Identifier =

== Description ==

The [wiki:Identifier] is a construct to identify the class of an object. All classes derived from OrxonoxClass have an Identifier, representing the class in the running game. The Identifier additionally stores all objects of its class in a [wiki:ObjectList list], knows the name of the class, can have a [wiki:ClassFactory], knows all parents and children, stores [wiki:ConfigValueContainer config-values] and shell-functions and provides several other functionalities.

You can get the Identifier of a given class with the macro Class(classname). If you only know the string, so if the class isn't hardcoded, use the macro ID("classname"). You have to include [wiki:CoreIncludes CoreIncludes.h] to use the macros.

A new class that wants an Identifier must use a macro (!RegisterObject(classname) or !RegisterRootObject(interfacename)) from [wiki:CoreIncludes]. Read the related Wiki-page for more informations.

[wiki:Identifier Identifiers] can be compared by using functions like isA(...) or isChildOf(...) to retrieve informations about the class-hierarchy.

You can't create an Identifier directly, because it's an abstract class. There only exist [wiki:ClassIdentifier ClassIdentifiers], but you can't create them too, because they have private constructors. Identifiers are created by [wiki:IdentifierDistributor], a helper class to warrant the uniqueness of an Identifier for a class.

The [wiki:SubclassIdentifier] is a class, that can store and act like an Identifier, but has a given base-class. Read the related Wiki-page for more informations.

== Functions ==

 * '''Macro''': (Include [wiki:CoreIncludes CoreIncludes.h] to use this)
   * Identifier* myidentifier = Class(BaseObject);
   * Identifier* myidentifier = ID("BaseObject");

 * '''Comparison''':
   * ''myidentifier'''''->isA('''''other''''')''': Compares the Identifier (''myidentifier'') with another Identifier (''other''). If ''myidentifier'' represents exactly the same or an inheriting class, the function returns true.
   * ''myidentifier'''''->isExactlyA('''''other''''')''': If ''myidentifier'' and ''other'' represent both the same class, the function returns true.
   * ''myidentifier'''''->isChildOf('''''other''''')''': If the class represented by ''myidentifier'' is a child of the class represented by ''other'', the function returns true.
   * ''myidentifier'''''->isDirectChildOf('''''other''''')''': Like isChildOf(...), but the class represented by ''myidentifier'' must be inherited directly without other classes between (class ''myidentifierclass'' : public ''otherclass'').
   * ''myidentifier'''''->isParentOf('''''other''''')''': If the class represented by ''myidentifier'' is a parent of the class represented by ''other'', meaning the other class is a child, the function returns true.
   * ''myidentifier'''''->isDirectParentOf('''''other''''')''': Like isParentOf(...), but the class represented by ''myidentifier'' must be a direct parent without other classes between (class ''otherclass'' : public ''myidentifierclass'').

 * '''Fabricate''':
   * fabricate() returns a new object of the class represented by the Identifier (see [wiki:ClassFactory]).

 * '''Name''':
   * getName() returns the name of the represented class.

 * '''Class-hierarchy''': You can retrieve lists and iterators (begin and end) of:
   * '''parents''': getParents(), getParentsBegin(), getParentsEnd()
   * '''directParents''': getDirectParents(), getDirectParentsBegin(), getDirectParentsEnd()
   * '''children''': getChildren(), getChildrenBegin(), getChildrenEnd()
   * '''directChildren''': getDirectChildren(), getDirectChildrenBegin(), getDirectChildrenEnd()

== Examples ==

The following examples use the class-tree below.

{{{
#!cpp
Identifier* myidentifier = Class(A1);            // Assigns the Identifier of A1

myidentifier->isA(Class(BaseObject));            // returns true
myidentifier->isA(Class(A1));                    // returns true
myidentifier->isA(Class(A1B1));                  // returns false
myidentifier->isA(Class(A2));                    // returns false
Class(A3)->isA(Class(Interface1));               // returns true

Class(A1B1)->isChildOf(Class(BaseObject));       // returns true
Class(A1B1)->isChildOf(Class(A1));               // returns true

Class(A1B1)->isDirectChildOf(Class(BaseObject)); // returns false
Class(A1B1)->isDirectChildOf(Class(A1));         // returns true

// Assigns the Identifier of the class with name "A2"
std::string name = "A2";
Identifier* other = ID(name);
}}}

{{{
#!cpp
// Creates a new instance of A1
BaseObject* newobject = Class(A1)->fabricate();

// Creates a new instance of A1 and casts it to Interface1
Identifier* myidentifier = Class(A3);
Interface1* newobject = (Interface1)(myidentifier->fabricate());
}}}

{{{
#!cpp
Identifier* myidentifier = Class(BaseObject);
for (std::list<const Identifier*>::const_iterator it = myidentifier->getDirectChildrenBegin(); it != myidentifier->getDirectChildrenEnd(); ++it)
  cout << (*it)->getName() << std::endl;

/*
returns all direct children of BaseObject:
A1
A2
A3
*/
}}}

[[Image(Core:testclass_interface_tree.gif)]]

== Networking ==

Because [wiki:Identifier Identifiers] use pointers, they are not qualified for networking. It's possible to just send the classname and use the [wiki:Factory], but this is expensive. That's why there's a network ID.

The network ID is an unsigned integer. You can retrieve an [wiki:Identifier] with a given network ID by using the macro ID(int) (include [wiki:CoreIncludes CoreIncludes.h] to use it). It's not determined which network ID belongs to which Identifier. This changes from version to version and from system to system, depending on the number of existing classes and the code executed before main(). So ID(5) might be different on each client. That's why the server has to synchronize the network ID's.

You can retrieve the network ID of an [wiki:Identifier] with getNetworkID().[[br]]
You can set the network ID of an [wiki:Identifier] with setNetworkID(int).

After changing the network ID of an Identifier to ''newid'', there might be two Identifiers with the ID ''newid''. ID(''newid'') will then return the changed Identifier and not the old one.

Read the Wiki-page of [wiki:Factory] to get more informations about how to iterate through all [wiki:Identifier Identifiers].

== Technical informations ==

---to come---