Defined in Class.Def Inherits from Object Inherits from Ordered Telescript sendable
Every package you write includes a citation object, which identifies your package to the world.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
You will usually use Citation objects in conjunction with your software packages. See the chapter on class SoftwarePackage for more information.
Citation objects simply identify your package, by including its author, its title, and its version number. You won't interact with citations, though the wireline will.
Instantiate: sometimes Subclass: rarely Call its methods: rarely
You'll probably never call any of the methods of class Citation , though you will include a citation object in every package you write. You will just add the citation object to your object definition file and fill in its fields.
Class Citation has the following methods that you might call:
| Method | Description |
|---|---|
| Author | Return the contents of the author field |
| SetAuthor | Set the author field |
| Title | Return the title field |
| SetTitle | Set the title field |
| MajorEdition | Return the major edition field |
| SetMajorEdition | Set the major edition field |
| MinorEdition | Return the minor edition field |
| SetMinorEdition | Set the minor edition field |
| Init | Set the title field of the citation |
| Initialize | Part of the initialization for a class |
| IsMatch | Return true if the compared citation has the same author, title, and edition | numbers |
| IsPeer | Return true if the authors of both citations have equal authority |
| MatchesInstance | Return true if the compared citation has the same author, title, and edition | numbers |
| Order | Return 0 |
Class Citation defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| Title | Identifier | The title of this particular item (usually a package) |
| Author | Telename | The author of this item |
| MajorEdition | Unsigned | The major version number |
| MinorEdition | Unsigned | The minor version number |
Class Citation defines the following fields:
| Field | Type | Description |
|---|---|---|
| title | Identifier | An identifier for the package |
| author | Object | An identifier for the author, often an address card |
| majorEdition | Unsigned | Major revision number |
| minorEdition | Unsigned | Minor revision number |
The Identifier object is a unique package identifier for the wireline. It has no fields. Just set its name to something indicative of your package.
The author field of the citation contains a Telescript\xaa object called a Telename. Telescript uses Telenames as part of its scheme to allow objects to have unique names.
Telenames have two fields: an authority and an identity. The authority identifies the person or authority who is responsible for the object with this telename. For your Magic Cap packages, the authority should probably be the organization responsible for the software. Once a given organization has an authority associated with it, the identity field of the telename is used to distinguish objects from a given authority.
Give your package a unique identifier if you want to send your package's classes over the wireline.
Magic Cap sends instances of package classes, but not package class definitions. Instead, Magic Cap sends a reference to the class and the package which defines it. The reference contains the package author's telename. When another device receives the instances, it uses the reference to match the instances with the correct class definition.
For Telescript 1.0, the authority is a 17 byte sequence which is generated using algorithms General Magic has built on top of code licensed from RSA. This software is built into every Magic Cap device and is used to personalize the device so that each device has a unique name for purposes of communicating with AT&T PersonaLink. This unique name is a telename which has an authority generated from the RSA algorithm.
Use Magic Cap on the Macintosh to generate an authority for your package's telename.
Version Note: The procedure described in this section is Macintosh and MPW specific. It will change as the Magic Cap development environment changes.Personalize Magic Cap with the name of the person or organization you'd like to use for your authority. Don't use any option-key shortcuts.
Bring up the inspector, and use it to find the name card you just created. Click the mouse on the first instance of a NameCard object, which should be just below an IndexTab object. The Inspector will display the name card you just created.
Dump the name card by choosing "Dump Inspector Target Deep" from the Examine menu in Magic Cap. Magic Cap's log file will now contain the text version of the name card and all its contained objects.
Switch to MPW. Search Magic Cap's log file for the string "assignedName". You should find an assignedName field in an AddressCard object similar to this one:
Instance AddressCard $84002506;
addresses: (ObjectList $84002507);
assignedName: (Telename $8420251A);
category: 2;
credentialsList: nilObject;
displayView: nilObject;
facilityList: nilObject;
lastChange: (Time $84202503);
magicName: (MagicmailName $84002508);
nativeLanguage: nilObject;
nickname: nilObject;
preferredPlatform: nilObject;
lastLabel: nilObject;
image: {6,220}; // (Image 4511)
End Instance;
The assignedName field will contain a Telename. Find that Telename in the log output. It will look something like this:
Instance Telename $8420251A;
authority: (OctetString $8420251B);
identity: nilObject;
End Instance;
You should use this Telename as your package's author.
The authority field of the telename contains an OctetString. Find that octet string in the log output.
Instance OctetString $8420251B;
extra: $ 00DF 06E4 4CB0 CC73 2B2E AB2B 71CD 2EC4 4C;
End Instance;
Use that OctetString object as your Telename's authority.
You should create an octet string as an identity object for each of your packages. The identity's octet string can be a plain text string, like this one:
Instance OctetString 44;
data: 'Fred's Package';
End Instance;
For convenience's sake, you might want to make this string the same as the name of your package identifier. The identity field of the Telename should be unique for each package you create. It is up to you to generate the identity field so that it is unique for each of your packages.
Here's what your completed citation might look like:
Instance Citation 40;
title: (Identifier 'My Little Package' 41);
author: (Telename 42);
majorEdition: 1;
minorEdition: 0;
End Instance;
Instance Identifier 'My Little Package' 41;
End Instance;
Instance Telename 42;
authority: (OctetString 43);
identity: (OctetString 44);
End Instance;
Instance OctetString 43; // your company's unique id
extra: $ 00DF 06E4 4CB0 CC73 2B2E AB2B 71CD 2EC4 4C;
49;
End Instance;
Instance OctetString 44; // your package's unique id
data: 'My Little Package';
End Instance;
You'll probably never call any methods of class Citation, so this version of the documentation does not include complete method descriptions.
operation IsPeer(other: Citation): Boolean, noFail; Call: sometimes Override: rarely
Call IsPeer to find out if two citations are peers, that is, they have authors that identical authorities.
operation IsMatch(other: Object): Boolean; Call: sometimes Override: rarely
Call IsMatch to find out if two citations match, that is, if they're equal.
overrides Initialize Call: rarely Override: rarely
Overriden to allow creation of citations from Telescript code.
overrides Init Call: rarely Override: rarely
Overriden to create an empty identifier for the title when a citation is created.
overrides Order Call: rarely Override: sometimes
Overridden to define ordering for citations (not implemented; always returns 0).