Book Contents Previous Chapter Next Chapter
This chapter describes interplatform content formats, usually called ICF, a set of classes that define standards for exchanging telecard elements across platforms. You may be interested in the information in this chapter if users might send objects of your package classes on telecards. Before reading this chapter, you should be familiar with viewables.
The information in this chapter is provided as an overview to familiarize you with basic ICF concepts. For complete information about ICF, see the book Developer's Guide to ICF.
Magic Cap defines a set of classes, the ICF classes, that allow elements of telecards to be represented by platform-independent information. When the user is about to send a telecard, Magic Cap attempts to translate the objects on the telecard into ICF objects, then sends the telecard containing the ICF objects. When the telecard is received, Magic Cap reverses the process, translating the ICF objects into Magic Cap classes.
As a platform-independent representation of message elements, you can use ICF for either of the following purposes:
The first purpose, making Magic Cap package classes with exchangeable objects, is described in an overview in this chapter and in detail in the book Developer's Guide to ICF. The second purpose listed above, making a non-Magic Cap electronic mail client, requires additional information and assistance from General Magic.
As described above, Magic Cap provides its own implementation of the ICF classes. So, when the objects on a telecard are translated from Magic Cap to ICF, they are actually translated from one set of Magic Cap classes to another. Although this translation may seem redundant, it keeps ICF separate from Magic Cap so that ICF can remain a standard even if Magic Cap's implementation changes.
When an object is about to be translated to ICF, Magic Cap calls its ICFContainerClass operation to determine which ICF class will be used to represent the object. Then, Magic Cap calls AddToContainer to translate the object. You should override ICFContainerClass and AddToContainer if you want objects of your package classes to be translated to ICF.
In your overridden ICFContainerClass operation, you should simply return the class number of the ICF class that your package class objects will be translated to. Magic Cap provides a set of ICF container classes for the most common telecard elements; see Developer's Guide to ICF for the complete list. Following is an example of an ICFContainerClass implementation for a class that is similar to Magic Cap's class Image:
Method ulong
PackageCustomImage_ICFContainerClass(ObjectID self)
{
// Our package class objects can be expressed
// as images, to translate them as such
#pragma unused (self)
return ImageElement_;
}
This example method returns ImageElement, an ICF class that represents images in general and can be used for Magic Cap images.
In your overridden AddToContainer operation, you should get the appropriate information from the object to be translated, convert it as necessary, and put it into the ICF container. You should call AddToDocument in your overridden AddToContainer operation to add each element to the container.
Some elements, such as colors in Magic Cap, contain platform-specific data that can't be easily represented on other platforms. You can add platform-specific data elements to your ICF object by calling AddPlatformObject or AddPlatformLong. These methods provide information that identifies the elements by their Magic Cap class name. If a platform-specific Magic Cap element is received on another Magic Cap platform and translated from ICF, it will be restored to its original form.
Following is an example of an AddToContainer implementation for a class that is a simplified version of Magic Cap's class Stamp:
Method void
CustomStamp_AddToContainer(ObjectID self, ObjectID container)
{
ObjectID image, sound;
ulong color;
// Always call Inherited at start of
// AddToContainer override
InheritedAddToContainer(self, container);
// Get stamp's image and sound
image = Image(self);
sound = Sound(self);
// Add stamp's image and sound to ICF container
// by calling AddToDocument with setter
if (image != nilObject)
SetImage(container, AddToDocument(image, container));
if (sound != nilObject)
SetSound(container, AddToDocument(sound, container));
// Add stamp's color to ICF container
// as a platform value
color = FieldOf(self, Viewable_color);
AddPlatformLong(container, color);
}
When an object is about to be translated from ICF to a standard Magic Cap class, Magic Cap calls its MagicCapClass operation to determine which Magic Cap class will be used to represent the object. Then, Magic Cap calls ExtractFromContainer to translate the object. You should override ExtractFromContainer if you want objects of your package class to be translated from ICF. You might override MagicCapClass if you want objects of your package class to use a different Magic Cap class than that defined by its superclass.
In your overridden ExtractFromContainer, you should get the appropriate information from the object to be translated, convert it as necessary to native Magic Cap format, and put it into the Magic Cap object. Following is an example of an ExtractFromContainer implementation for a class that is a simplified version of Magic Cap's class Stamp:
Method void
CustomStamp_ExtractFromContainer(ObjectID self, ObjectID container, ObjectID superview)
{
ObjectID image, sound;
ulong color;
// Always call Inherited at start of
// ExtractFromContainer override
InheritedExtractFromContainer(self, container, superview);
// Get stamp's image and sound
image = Image(container);
sound = Sound(container);
SetImage(self, ExtractFromDocument(image, nilObject, self, false));
SetSound(self, ExtractFromDocument(sound, nilObject, self, false));
// Restore color from platform value
if (PlatformObjects(container) != nilObject)
{
ulong newColor = NextPlatformLong(container);
}
SetFieldOf(self, Viewable_color, newColor);
}
For complete information on ICF, see the book Developer's Guide to ICF.
For more information, see these topics in Magic Cap Class and Method Reference:
class Object
operations and attributes:
AddToContainer AddToDocument ExtractFromContainer ICFContainerClass
class ICFContent
operations and attributes:
AddPlatformLong AddPlatformObject MagicCapClass
Book Contents Previous Chapter Next Chapter