Storage

Inside Macintosh: OpenDoc Class Reference / Part 2 - Types and Constants

Storage
This section describes the types used by the OpenDoc storage system.

Object IDs
The following types and constants are used in many storage operations.

ODID
A 32-bit value used as an identifier for a particular type of object (for example, a document or a storage unit).

Constants of this type

kODNULLID
A null ID or an invalid ID.
kODIDAll
Any ID. This value is used when specifying which storage units (or other objects) are of interest to a particular operation.
kODIDWild
Any ID. This value is used when specifying which storage units (or other objects) are of interest to a particular operation.

Note that these three constants have the same value; their different names provide clarity to the code that uses them. Typically kODNULLID is used to mean an absent or invalid ID. kODIDAll or kODIDWild are used to specify no restrictions on the scope of a cloning operation.

ODPersistentObjectID
A 32-bit identifier, used for scripting, of a part or frame.
Container Suites and Storage Containers
The following types and constants relate to container suites. Types and constants marked [M] are specific to the Mac OS platform.

ODContainerID
A structure of type ODByteArray (page 877) identifying a container. The buffer of this byte array holds a container-suite-specific identifier for a container. The structure of the buffer depends on the type of container. For example, the identifier for a file container specifies a file-system file; the identifier for a memory container is a handle for a relocatable memory block.
ODContainerName
A user-readable name of type ODName (page 876) for a container object.
ODContainerSuite
An opaque type representing a specific container suite.
ODContainerType
A string of type ODISOStr (page 875) used to specify a type of storage container.

Constants of this type

kODBentoFileContainer
The Bento container class for documents.
kODBentoMemoryContainer
The Bento container class for drag and drop and the clipboard.
kODDefaultFileContainer
The default container type for documents on this platform.
kODDefaultMemoryContainer
The default container type for drag and drop and the clipboard on this platform.

On each platform, OpenDoc has a default container type that it uses for documents and a default container type that it uses for drag and drop and the clipboard. On the Mac OS, these defaults are the Bento file container and the Bento memory container, respectively.
ODOSType [M]
A 32-bit wrapper for a Mac OS OSType structure, which specifies a Mac OS file type.

Constants of this type

kODShellSignature [M]
The creator type for the OpenDoc document shell (value 'odtm').
kODNameMappings [M]
The resource type designation for the name-mapping resource (value 'nmap').

Documents
The following types and constants relate to OpenDoc documents.

ODDocumentIDAn identifier of type ODID (page 899) for a document. Use
the ODID constant kODNULLID to represent a null document ID.

Constants of this type

kODDefaultDocument
The default document ID.
ODDocumentName
A user-readable name of type ODName (page 876) for a document.

Drafts
The following types and constants relate to drafts.

ODDraftID
An identifier of type ODID (page 899) for a draft. Use the ODID constant kODNULLID to represent a null draft ID.
ODDraftKey
A 32-bit value used as an identifier for a cloning transaction.
ODDraftName
A name of type ODISOStr (page 875) for a draft.
ODDraftPermissions
An enumeration specifying the possible values for draft permissions.
Constants of this type

kODDPExclusiveWrite
Exclusive read/write access.
kODDPNone
No access.
kODDPReadOnly
Read-only access.
kODDPSharedWrite
Shared read/write access.
kODDPTransient
Navigation-only access.

The Bento container suite supports only the kODDPReadOnly and kODDPExclusiveWrite draft permissions.

Storage Units
The following types and constants relate to storage units, which are used for storage and data transfer.

ODObjectType
A string of type ODType (page 876) specifying the type of persistent object represented by a particular storage unit.
Constants of this type

kODFrameObject
A frame.
kODNonPersistentFrameObject
A nonpersistent frame.
kODPartObject
A part.
ODStorageUnitID
An identifier of type ODID (page 899) for a storage unit. Use the ODID constant kODNULLID to represent a null storage-unit ID.
ODStorageUnitKey
A 32-bit value used as an access key for locking and unlocking a storage unit.
Constants of this type

kODNULLKey
A storage unit key has not yet been granted or could not be granted.
ODStorageUnitName
A name of type ODISOStr (page 875) for a storage unit.
ODStorageUnitRef
An opaque type representing a persistent reference for a storage unit. Whereas a value of the ODStorageUnitID type identifies a storage unit within the current session, a value of the ODStorageUnitRef type identifies it persistently across sessions.
Related constants

kODStorageUnitRefSize
The size (number of bytes) of an ODStorageUnitRef.

A value of the ODStorageUnitRef type is created by a storage unit, which must be focused on the value where the persistent reference will be stored. The scope of the persistent reference is limited to the value for which it was created; if you store it in a different value, it will almost certainly not refer to the correct storage unit. For more information on persistent references to storage units, see the chapter on storage in the OpenDoc Programmer’s Guide for the MacOS.

Properties and Values
The following types and constants relate to the properties and values in a storage unit.

ODPropertyName
A name of type ODISOStr (page 875) for a property within a storage unit. The section "Property Names" on page 905 describes the constants defined for this type.
ODValueIndex
A 32-bit integer used as an index for a value within a property of a storage unit. The first value created for a property has index 1; the second, 2; and so on.
Constants of this type

kODIndexAll
Any value index. This constant is used when focusing a storage unit on a property and when checking for the existence of a property in a storage unit.
ODValueType
A string of type ODType (page 876) used to identify the type of data in the value of a storage unit. The section "Value Types" on page 912 describes the constants defined for this type.

Property Names
This section describes the constants defined for the ODPropertyName type (page 904). These constants are names of the standard OpenDoc properties used in storage units, or prefixes used to construct property names.

Prefixes
The following constants are prefixes in property names; they specify the type of information stored in the property.

kODPropPreAnnotation
The prefix in the names of all annotation properties. An annotation is a property that should be copied automatically whenever the storage unit is cloned. Part-editor developers can use this string as a prefix in the names of annotation properties they define.
kODPropPreODMetaData
The prefix in the names of all OpenDoc metadata properties. Metadata is information about the data itself, such as the time it was last modified. Part-editor developers should not use this prefix.

Draft Properties
The following properties save the specified information about the draft. Properties marked [M] are specific to the Mac OS platform.

kODPropDraftComment
Any user-created comments on the draft; value type kODMacIText.
kODPropDraftNumber
The number of this draft; value type kODSLong.
kODPropDraftSavedDate
The draft-saved date for drafts that were saved via the Draft History dialog box; value type kODTime_T.
kODPropEditionID [M]
The last edition file ID used by the current draft of the document; value type kODULong.
kODPropSectionID [M]
The last section ID used by the current draft of the document; value type kODULong.
kODPropRootFrameList
A list of strong references to the root frames of saved windows; value type kODStrongStorageUnitRefs.
kODPropRootPartSU
A strong reference to the root part of this draft; value type kODStrongStorageUnitRef.

Persistent-Object Properties
The following properties are used by persistent objects of all kinds.

kODPropObjectType
The type of persistent object (for example, part or frame); value type kODISOStr.
kODPropStorageUnitType
The type of storage unit (for example, the storage unit for a frame object, for link content, and so forth); value type kODISOStr.

Part Properties
The following properties save the specified information about parts.

kODPropComments
Any user-created comments about the part; value type kODMacIText.
kODPropContents
The stored intrinsic data for the part; the value types correspond to part kinds supported by the part.
kODPropCreateDate
The date and time when the part was created; value type kODTime_T.
kODPropCustomIcon
The custom icon for a part; value type kODIconFamily. If the part has a custom icon, the custom icon is stored in this property.
kODPropDisplayFrames
A list of weak references to the display frames of this part; value type kODWeakStorageUnitRefs.
kODPropIsStationery
Specifies whether this part is a stationery part; value type kODBoolean.
kODPropModDate
The date and time when the part was last modified; value type kODTime_T.
kODPropModUser
The user name when the part was last modified; value type kODMacIText.
kODPropName
The name of the part; value type kODMacIText.
kODPropPageSetup
Page setup information to be used by a root part running a print job. The value type is platform-specific; on the Mac OS, either kODTypeQuickDrawPageSetup or kODTypeGXPageSetup.
kODPropPreferredEditor
The editor ID of the preferred editor (the editor that last wrote this part to persistent storage); value type kODEditor.
kODPropPreferredKind
The value in the kODPropContents property that should be read by an editor bound to this part; value type kODISOStr.

Frame Properties
The following properties save the specified information about frames.

kODPropBiasTransform
The bias transform to be attached to the canvas on which this frame is drawn; value type kODTransform.
kODPropContainingFrame
A weak reference to the containing frame of this frame; value type kODWeakStorageUnitRef.
kODPropDoesPropagateEvents
Specifies whether this frame's part propagates events; value type kODBoolean.
kODPropFrameGroup
The group ID of the frame group to which this frame belongs; value type kODULong.
kODPropFrameShape
The frame shape for this frame; value type kODPolygon.
kODPropGraphicsSystem
The graphics system used to draw in this frame's part; value type kODSShort. The stored data is interpreted as type ODGraphicsSystem (page 883).
kODPropInternalTransform
The internal transform for this frame; value type kODTransform.
kODPropIsFrozen
Specifies whether this frame is bundled; value type kODBoolean.
kODPropIsOverlaid
Specifies whether this frame is overlaid; value type kODBoolean.
kODPropIsRoot
Specifies whether this frame is the root frame of a window; value type kODBoolean.
kODPropIsSubframe
Specifies whether this frame is a subframe of another frame; value type kODBoolean.
kODPropLinkStatus
The link status of this frame; value type kODULong, interpreted as type ODLinkStatus (page 882).
kODPropPart
A strong reference to the part displayed in this frame; value type kODStrongStorageUnitRef.
kODPropPartInfo
The part info (part-specific data) stored with this frame. The value type is determined by the part editor.
kODPropPresentation
The presentation of the part displayed in this frame; value type kODISOStr.
kODPropSequenceNumber
The sequence number of this frame within its frame group; value type kODULong.
kODPropViewType
The view type of the part displayed in this frame; value type kODISOStr.
kODPropWindowProperties
A strong reference to a storage unit containing window size and so forth; value type kODStrongStorageUnitRef. This property is added to the root frame of a saved window.

Window Properties
The following properties save the specified information about windows. Properties marked [M] are specific to the Mac OS platform

kODPropRootFrame
A strong reference to the root frame; value type kODStrongStorageUnitRef.
kODPropShouldShowLinks
Specifies whether parts in this window should display link borders; value type kODBoolean.
kODPropSourceFrame
A strong reference to the source frame; value type kODStrongStorageUnitRef.
kODPropWindowHasCloseBox
Specifies whether this window has a close box; value type kODBoolean.
kODPropWindowHasZoomBox
Specifies whether this window has a zoom box; value type kODBoolean.
kODPropWindowIsFloating
Specifies whether this window can float; value type kODBoolean.
kODPropWindowIsResizable
Specifies whether this window has a resize box; value type kODBoolean.
kODPropWindowIsRootWindow
Specifies whether this window is a root window; value type kODBoolean.
kODPropWindowIsVisible
Specifies whether this window is visible; value type kODBoolean.
kODPropWindowProcID [M]
The Mac OS definition ID of the window; value type kODSShort.
kODPropWindowRect
The bounding rectangle of a window; value type kODRect.
kODPropWindowRefCon
The window's reference constant, which is set by your part; value type kODSLong.
kODPropWindowTitle
The title of a window; on the Mac OS, the value type is kODMacIText.

Data-Transfer Properties
The following properties save the specified information in the content storage units of data-transfer objects (the clipboard, the drag-and-drop object, link-source objects, and link objects).
General

kODPropContents
The data being transferred in the same format as in the storage unit of the source part; the value types correspond to the types (part kinds) of the data being transferred.
kODPropContentFrame
A weak reference to the embedded frame being transferred; value type kODWeakStorageUnitRef. This property exists only if the data being transferred consists of a single embedded frame.
kODPropName
If the transferred data is embedded at the destination, the name to be used for the resulting embedded part; value type kODMacIText.
kODPropProxyContents
Suggested adornments to apply to the embedded frame being transferred; value type depends on type of adornment being transferred. This property exists only if the data being transferred consists of a single embedded frame.
kODPropSuggestedFrameShape
If the transferred data is embedded at the destination, the suggested shape for the resulting embedded frame; the value type is either kODPolygon or a platform-specific value type.
kODPropCloneKindUsed
The kind of cloning operation used to clone objects into this data-transfer object; value type kODCloneKind.
Clipboard or drag and drop

kODPropLinkSpec
A link specification; value type kODLinkSpec. This property indicates that the destination part may paste a link to the original content being transferred.
Drag and drop

kODPropMouseDownOffset
The offset of the location at which a mouse-down event occurred from the top left corner of the selection; value type kODPoint.
Link object

kODPropLinkSource
A weak reference to the link-source object associated with this link object; value type kODWeakStorageUnitRef.
Link-source object

kODPropAutoUpdate
Specifies whether this link is to be updated automatically; value type kODBoolean.
kODPropChangeTime
The date and time when this link was last updated; value type kODTime_T.
kODPropLink
A weak reference to the link object associated with this link-source object; value type kODWeakStorageUnitRef.
kODPropLinkContentSU
A strong reference to the content storage unit for the linked data; value type kODStrongStorageUnitRef.
kODPropSourcePart
A weak reference to the part that contains (or last contained) the source data for this link; value type kODWeakStorageUnitRef.

Value Types
This section describes the constants defined for the ODValueType type (page 904).
The following value-type constants specify the standard types in which data can be stored in values of storage units. Constants marked [M] are specific to the Mac OS platform.

kODBoolean
Type ODBoolean (page 878).
kODCloneKind
Type ODCloneKind (page 917), expressed as a 32-bit value.
kODEditor
Type ODEditor (page 929).
kODIconFamily
Type ODIconFamily (page 880).
kODIconFamilyMac [M]
Type ODIconFamily (page 880) representing a Mac OS icon family.
kODIconFamilyWin
Type ODIconFamily (page 880) representing a Windows icon family.
kODIconFamilyOS2
Type ODIconFamily (page 880) representing an OS/2 icon family.
kODIconFamilyAIX
Type ODIconFamily (page 880) representing an AIX icon family.
kODIntlText
Type ODIText (page 875) converted to a fully decomposed document-interchange format that corresponds to ISO standard 10646-1, 1993.
kODISOStr
Type ODISOStr (page 875).
kODISOStrList
A list of ISO strings, each of type ODISOStr (page 875).
kODLinkSpec
Link-specification data for an ODLinkSpec object (page 390).
kODMacIText [M]
Type ODIText (page 875) in traditional Mac OS international text format.
kODObjectType
Type ODObjectType (page 903).
kODPoint
Type ODPoint (page 885).
kODPolygon
Type ODPolygon (page 886).
kODRect
Type ODRect (page 885).
kODSLong
Type ODSLong (page 874).
kODSShort
Type ODSShort (page 874).
kODStrongStorageUnitRef
Type ODStorageUnitRef (page 903) representing a strong storage-unit reference.
kODStrongStorageUnitRefs
A list of strong storage-unit references, each of type ODStorageUnitRef (page 903).
kODTime_T
Type ODTime (page 877).
kODTransform
Type ODMatrix (page 888).
kODTypeGXPageSetup [M]
The QuickDraw GX type gxJob.
kODTypeQuickDrawPageSetup [M]
The QuickDraw type THPrint.
kODULong
Type ODULong (page 878).
kODUShort
Type ODUShort (page 878).
kODWeakStorageUnitRef
Type ODStorageUnitRef (page 903) representing a weak storage unit reference.
kODWeakStorageUnitRefs
A list of weak storage unit references, each of type ODStorageUnitRef (page 903).

The following value-type constant is used when focusing a storage unit on a property and when checking for the existence of a property in a storage unit.

kODTypeAll
All value types. This constant is equivalent to kODNULL. Their different names provide clarity to the code that uses them. Typically kODNULL is used to mean an absent or invalid value type; kODTypeAll is used to specify all values of a given property.

Position Codes
Position codes represent either the position of drafts within a document or the position of properties and values within a storage unit.

ODPositionCode
A 32-bit value used to specify the position of a draft within a document, or the position of a property or value that defined the focus context for a storage unit.

Draft Position Codes
The following constants of the ODPositionCode type represent positions of one draft in a document relative to another draft of the same document. The drafts of a document can be thought of as a stack with the most recent on top; a given draft is said to be above an earlier draft and below a more recent draft.

kODPosFirstAbove
The draft above (immediately more recent than) the specified draft.
kODPosFirstBelow
The draft below (immediately previous to) the specified draft.
kODPosLastAbove
The draft above (immediately more recent than) the specified draft.
kODPosLastBelow
The draft below (immediately previous to) the specified draft.
kODPosSame
The same draft as the specified draft.
kODPosTop
The top (most recent) draft in the document.

Storage-Unit Position Codes
The following constants of the ODPositionCode type represent positions of properties and values within a storage unit; they are used to define or to change the focus context of a storage unit.

kODPosAll
All properties or all values.
kODPosFirstSib
The first property of the storage unit or the first value of the specified property.
kODPosLastSib
The last property of the storage unit or the last value of the specified property.
kODPosMWrap
Wraps iteration of properties or values.
kODPosNextSib
The next property of the storage unit or the next value of the specified property, relative to the current focus context.
kODPosPrevSib
The previous property of the storage unit or the previous value of the specified property, relative to the current focus context.
kODPosSame
The same property or value context as in the current focus context.
kODPosUndefined
Undefined property or value context; typically used when a property name specifies the property and when a value type or value index specifies the value.

Unused Position Codes
The following constants of type ODPositionCode are reserved for future use.

kODPosReserved11
Reserved for future use.
kODPosReserved12
Reserved for future use.
kODPosReserved13
Reserved for future use.
kODPosReserved14
Reserved for future use.
kODPosReserved15
Reserved for future use.