Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 6 - Component Manager / Component Manager Reference

Routines for Components / Managing Component Connections

SetComponentInstanceStorage

When an application or component opens a connection to your component, the Component Manager sends your component an open request. In response to this open request, your component should set up an environment to service the connection. Typically, your component should allocate some memory for the connection. Your component can then use that memory to maintain state information appropriate to the connection.

The SetComponentInstanceStorage procedure allows your component to pass a handle to this memory to the Component Manager. The Component Manager then provides this handle to your component each time the client application requests service from this connection.

PROCEDURE SetComponentInstanceStorage 
      (aComponentInstance: ComponentInstance; theStorage: Handle);

aComponentInstance

The connection to associate with the allocated memory. The Component Manager provides a component instance to your component when the connection is opened.

theStorage

A handle to the memory that your component has allocated for the connection. Your component must allocate this memory in the current heap. The Component Manager saves this handle and provides it to your component, along with other parameters, in subsequent requests to this connection.

DESCRIPTION

The SetComponentInstanceStorage procedure associates the handle passed in the parameter theStorage with the connection specified by the aComponentInstance parameter. Your component should dispose of any allocated memory for the connection only in response to the close request.

SPECIAL CONSIDERATIONS

Note that whenever an open request fails, the Component Manager
always issues the close request. Furthermore, the value stored with SetComponentInstanceStorage is always passed to the close request, so
it must be valid or NIL. If the open request tries to dispose of its allocated memory before returning, it should call SetComponentInstanceStorage again with a NIL handle to keep the Component Manager from passing an invalid handle to the close request.

SEE ALSO

For an example that allocates memory in response to an open request, see Listing 6-6 on page 6-19.