Inside Macintosh: Sound /

Chapter 5 - Sound Components / Writing a Sound Component

Creating a Sound Component

A sound component is a component. It contains a number of resources, including icons, strings, and the standard component resource (a resource of type 'thng') required of any Component Manager component. In addition, a sound component must contain code to handle required selectors passed to it by the Component Manager as well as selectors specific to the sound component.

Note

For complete details on components and their structure, see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox. This section provides specific information about sound components.

The component resource binds together all the relevant resources contained in a component; its structure is defined by the ComponentResource data type.

struct ComponentResource {
   ComponentDescription    cd;
   ResourceSpec            component;
   ResourceSpec            componentName
   ResourceSpec            componentInfo;
   ResourceSpec            componentIcon;
};

The component field specifies the resource type and resource ID of the component's executable code. By convention, this field should be set to the value kSoundComponentCodeType:

#define kSoundComponentCodeType     'sift'   /*sound component code type*/

(You can, however, specify some other resource type if you wish.) The resource ID can be any integer greater than or equal to 128. See the following section for further information about this code resource. The ResourceSpec data type has this structure:

typedef struct {
   OSType                  resType;
   short                   resID;
} ResourceSpec;

The componentName field specifies the resource type and resource ID of the resource that contains the component's name. Usually the name is contained in a resource of type 'STR '. This string should be as short as possible.

The componentInfo field specifies the resource type and resource ID of the resource that contains a description of the component. Usually the description is contained in a resource of type 'STR '.

The componentIcon field specifies the resource type and resource ID of the resource that contains an icon for the component. Usually the icon is contained in a resource of type 'ICON'.

The cd field of the ComponentResource structure is a component description record, which contains additional information about the component. A component description record is defined by the ComponentDescription data type.

typedef struct {
   OSType                  componentType;
   OSType                  componentSubType;
   OSType                  componentManufacturer;
   unsigned long           componentFlags;
   unsigned long           componentFlagsMask;
} ComponentDescription;

For sound components, the componentType field must be set to a value recognized by the Sound Manager. Currently, there are five available component types for sound components:

#define kSoundComponentType      'sift'   /*utility component*/
#define kMixerType               'mixr'   /*mixer component*/
#define kSoundHardwareType       'sdev'   /*sound output device component*/
#define kSoundCompressor         'scom'   /*compression component*/
#define kSoundDecompressor       'sdec'   /*decompression component*/

In addition, the componentSubType field must be set to a value that indicates the type of audio services your component provides. For example, the Apple-supplied sound output device components have these subtypes:

#define kClassicSubType          'clas'   /*Classic hardware*/
#define kASCSubType              'asc '   /*ASC device*/
#define kDSPSubType              'dsp '   /*DSP device*/

If you add your own sound output device component, you should define some other subtype.

Note

Apple Computer, Inc., reserves for its own use all types and subtypes composed solely of lowercase letters.

You can assign any value you like to the componentManufacturer field; typically you put the signature of your sound component in this field.

The componentFlags field of the component description for a sound component contains bit flags that encode information about the component. You can use this field to specify that the Component Manager should send your component the kComponentRegisterSelect selector.

enum {
   cmpWantsRegisterMessage    = 1L<<31 /*send register request*/
};

This bit is most useful for sound output device components, which might need to test for the presence of the appropriate hardware to determine whether to register with the Component Manager. When your component gets the kComponentRegisterSelect selector at system startup time, it should make sure that all the necessary hardware is available. If it isn't available, your component shouldn't register. See "Registering and Opening a Sound Component" beginning on page 5-16 for more information on opening and registering your sound component.

You also use the componentFlags field of the component description to define the characteristics of your component. For example, you can set a bit in that field to indicate that your sound component can accept stereo sound data. See "Specifying Sound Component Capabilities" on page 5-11 for more details on specifying the features of your sound component.

You should set the componentFlagsMask field to 0.

Listing 5-1 shows, in Rez format, a component resource for a sample sound output device component named SurfBoard.

Listing 5-1 Rez input for a component resource

#define kSurfBoardID                      128
#define kSurfBoardSubType                 'SURF'
resource 'thng' (kSurfBoardID, purgeable) {
   'sdev',                       /*component type*/
   kSurfBoardSubType,            /*component subtype*/
   'appl',                       /*component manufacturer*/
   cmpWantsRegisterMessage,      /*component flags*/
   0,                            /*component flags mask*/
   'sift',                       /*component code resource type*/
   kSurfBoardID,                 /*component code resource ID*/
   'STR ',                       /*component name resource type*/
   kSurfBoardID,                 /*component name resource ID*/
   'STR ',                       /*component info resource type*/
   kSurfBoardID+1,               /*component info resource ID*/
   'ICON',                       /*component icon resource type*/
   kSurfBoardID                  /*component icon resource ID*/
};

Your sound component is contained in a resource file. You can assign any type you wish to be the file creator, but the type of the file must be 'thng'. If the sound component contains a 'BNDL' resource, then the file's bundle bit must be set.