Programming Reference: Registration

# Programming Reference

## Registration

A registry is a table that maps data types to executable code. These tables represent the preferences of the user for particular part editors, scripting systems, and translators.

Several different registry objects are supported, including parts, scripting systems, and translations. Part registries allow the document shell to map parts to part editors according to their part kind. Scripting system registries determine what scripting system is used to edit and interpret a script. Translation registries regulate which translation module is used for translating data of a given part kind into data of a different part kind.

Name spaces are used to uniquely identify part kinds, translation module kinds, scripting systems, and object extensions for code-binding purposes. A name space associates an ISO string (for example, a part kind) with a pointer to the code (for example, the part editor for the part kind).

The following lists the registration functions in alphabetic order.

- ODDeregisterPartHandler
- ODDeregisterPartHandlerClass
- ODQueryCategoryList
- ODQueryHandlerDisplayName
- ODQueryKindDisplayName
- ODQueryPartHandlerInfo
- ODQueryPartHandlerList
- ODQueryPartKindInfo
- ODQueryPartKindList
- ODQueryPreferredPartHandler
- ODQueryPreferredPartHandlerForCategory
- ODQueryPreferredPartHandlerForFileExt
- ODQueryPreferredPartHandlerForFileType
- ODRegisterPartHandlerClass
- ODSetPreferredPartHandler
- ODSetPreferredPartHandlerForCategory
- ODSetPreferredPartHandlerForFileExt
- ODSetPreferredPartHandlerForFileType

### ODDeregisterPartHandler

This function deregisters a part handler with the OpenDoc registry and the OpenDoc SOM interface repository using the specified part handler name.

Signature

    unsigned long ODDeregisterPartHandler (ISOString isoPartHandlerName)

Parameters

isoPartHandlerName (ISOString) - input

  The name of the part handle to be deregistered.

Returns

rv (unsigned long) - returns

  Return codes.
  - NO_ERROR
  - ERROR_COULD_NOT_FIND_PART_HANDLER
  - ERROR_COULD_NOT_FIND_CLASS
  - ERROR_COULD_NOT_FIND_CLASS_IN_SOM_IR

### ODDeregisterPartHandlerClass

This function deregisters a part handler with the OpenDoc registry and the OpenDoc SOM interface repository using the specified class name.

Signature

    unsigned long ODDeregisterPartHandlerClass (ISOString className)

Parameters

className (ISOString) - input

  The name of the class of the part handler to be deregistered.

Returns

rv (unsigned long) - returns

  Return codes.
  - NO_ERROR
  - ERROR_COULD_NOT_FIND_PART_HANDLER
  - ERROR_COULD_NOT_FIND_CLASS
  - ERROR_COULD_NOT_FIND_CLASS_IN_SOM_IR

### ODQueryCategoryList

This function returns a list of category names that meet the given criteria. If the part handler name and part kind name are not specified, a list of all category names is returned.

Signature

    unsigned long ODQueryCategoryList (ISOString isoPartHandlerName,
                                       ISOString isoPartKind,
                                       ISOString buffer,
                                       ODULong bufferSize)

Parameters

isoPartHandlerName (ISOString) - input

  The part handler name for which information is to be returned.

isoPartKind (ISOString) - input

  The part kind for which information is to be returned.

buffer (ISOString) - output

  A list of category names, separated by commas.

bufferSize (ODULong) - input

  The buffer size for which information is to be returned.

Returns

rv (ODULong) - returns

  Return codes.
  - NO_ERROR
  - errPR_PART_KIND_NOT_FOUND
  - errPR_BUFFER_TOO_SMALL

### ODQueryHandlerDisplayName

This function returns a list of part handler names that meet the given criteria.

Signature

    unsigned long ODQueryHandlerDisplayName (ISOString PartHandlerName,
                                             ISOString buffer,
                                             ODULong bufferSize)

Parameters

partHandlerName (ISOString) - input

  The part handler name for which information is to be returned.

buffer (ISOString) - output

  A list of category names, separated by commas.

bufferSize (ODULong) - input

  The buffer size for which information is to be returned.

Returns

rv (ODULong) - returns

  Return codes.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL

### ODQueryKindDisplayName

This function returns a list of part kind names that meet the given criteria.

Signature

    unsigned long ODQueryKindDisplayName (ISOString PartKindName,
                                          ISOString buffer,
                                          ODULong bufferSize)

Parameters

partKindName (ISOString) - input

  The part kind name for which information is to be returned.

buffer (ISOString) - output

  A list of category names, separated by commas.

bufferSize (ODULong) - input

  The buffer size for which information is to be returned.

Returns

rv (ODULong) - returns

  Return codes.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL

### ODQueryPartHandlerInfo

This function returns information about the specified part handler.

Signature

    unsigned long ODQueryPartHandlerInfo (ISOString isoPartHandlerName,
                                          PartKindQueryInfo *partKindQueryInfo

Parameters

isoPartHandlerName (ISOString) - input

  The part handler for which information is to be returned.

partKindQueryInfo (PartKindQueryInfo *) - output

  Information about the specified part handler.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL
  - ERROR_COULD_NOT_FIND_PART_HANDLER

### ODQueryPartHandlerList

This function returns a list of part handler names that meet the given criteria. If the part kind and category are not specified, a list of all part handlers is returned.

Signature

    unsigned long ODQueryPartHandlerList (ISOString isoPartKind,
                                          ISOString buffer,
                                          ODULong bufferSize)

Parameters

isoPartKind (ISOString) - input

  The part kind that the part handlers can edit. This parameter is optional and can be set to kODNULL.

buffer (ISOString) - output

  A list of part handlers. This buffer contains the names separated by commas.

bufferSize (ODULong) - in/out

  On input, this parameter is the size, in bytes, of the buffer. On output, the actual size of the list of part handlers in the buffer is returned. If the buffer is too small, the size of the buffer required to hold the string is returned.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL

### ODQueryPartKindInfo

This function returns information about the specified part kind.

Signature

    unsigned long ODQueryPartKindInfo (ISOString isoPartHandlerName,
                                       ISOString isoPartKindName,
                                       PartKindQueryInfo *partKindQueryInfo)

Parameters

isoPartHandlerName (ISOString) - input

  The part handler name for which information is to be returned.

isoPartKindName (ISOString) - input

  The part kind for which information is to be returned.

partKindQueryInfo (PartKindQueryInfo *) - output

  A structure containing information about the part kind.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL
  - ERROR_COULD_NOT_FIND_PART_HANDLER

### ODQueryPartKindList

This function returns a list of part kinds that meets the given criteria. If the part handler and category are not specified, a list of all part-registered part kinds is returned.

Signature

    unsigned long ODQueryPartKindList (ISOString isoPartHandlerName,
                                       ISOString *buffer,
                                       ODULong bufferSize)

Parameters

isoPartHandlerName (ISOString) - input

  The part handler that can edit the part kinds. This parameter is optional and can be set to kODNULL.

buffer (ISOString *) - output

  A list of part kinds. This buffer contains the part kind names separated by commas.

  When it is finished using this value, the client code is responsible for freeing it by calling SOMFree.

bufferSize (ODULong) - in/out

  On input, this parameter is the size, in bytes of the specified buffer. On output, the actual size of the list of part kinds placed in the buffer is returned. If the buffer is too small, the size of the buffer required to hold the string is returned.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL

### ODQueryPreferredPartHandler

This function returns the preferred part-handler name for the specified part kind.

Signature

    unsigned long ODQueryPreferredPartHandler (ISOString isoPartKindName,
                                               ISOStr isoPartHandlerName
                                               ODULong bufferSize)

Parameters

isoPartKindName (ISOString) - input

  The part kind name.

isoPartHandlerName (ISOStr) - output

  A buffer in which the preferred part handler for the specified part kind is to be returned.

bufferSize (ODULong) - in/out

  On input, this parameter is the size, in bytes, of the specified buffer. On output, the actual size of the string placed in the buffer is returned. If the buffer size is too small, the size of the buffer required to hold the string is returned.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL
  - ERROR_COULD_NOT_FIND_PART_KIND

### ODQueryPreferredPartHandlerForCategory

This function returns information about the preferred part-handler using the specified category.

Signature

    unsigned long ODQueryPreferredPartHandlerForCategory (ISOString isoCategory,
                                                          ISOString isoPartHandlerName,
                                                          ODULong bufferSize)

Parameters

isoCategory (ISOString) - input

  The category of the part.

isoPartHandlerName (ISOString) - output

  A buffer in which the preferred part handler for the specified part category is to be returned.

bufferSize (ODULong) - input

  On input, this parameter is the size, in bytes, of the specified buffer. On output, the actual size of the string placed in the buffer is returned. If the buffer is too small, the size of the buffer required to hold the string is returned.

Returns

rv (unsigned long) - returns

  Return code.

### ODQueryPreferredPartHandlerForFileExt

This function returns information about the preferred part-handler using the specified file extension.

Signature

    unsigned long ODQueryPreferredPartHandlerForFileExt (ISOString isoFileExt,
                                                         ISOString isoPartHandlerName
                                                         ODULong bufferSize)

Parameters

isoFileExt (ISOString) - input

  The file extension of the part.

isoPartHandlerName (ISOString) - output

  A buffer in which the preferred part handler for the specified file extension is to be returned.

bufferSize (ODULong) - input

  On input, this parameter is the size, in bytes, of the buffer. On output, the actual size of the string placed in the buffer is returned. If the buffer is too small, the size of the buffer required to hold the string is returned.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL

### ODQueryPreferredPartHandlerForFileType

This method returns the preferred part-handler name for the specified file type.

Signature

    unsigned long ODQueryPreferredPartHandlerForFileType (ISOString partFileType,
                                                          ISOString isoPartHandlerName,
                                                          ODULong bufferSize)

Parameters

partFileType (ISOString) - input

  The file type of the part.

isoPartHandlerName (ISOString) - output

  A buffer in which the preferred part handler for the specified file type is to be returned.

bufferSize (ODULong) - input

  On input, this parameter is the size, in bytes, of the buffer. On output, the actual size of the string placed in the buffer is returned. If the buffer is too small, the size of the buffer required to hold the string is returned.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - errPR_BUFFER_TOO_SMALL

### ODRegisterPartHandlerClass

This function registers a part handler with the OpenDoc registry.

Signature

    unsigned long ODRegisterPartHandlerClass (ISOString className)

Parameters

className (ISOString) - input

  The name of the SOM class to be registered.

Returns

rv (unsigned long) - returns

  Return codes.
  - NO_ERROR
  - errPR_INVALID_CLASSNAME
  - errPR_COULD_NOT_LOAD_CLASS
  - errPR_NOT_PART_HANDLER_CLASS
  - errPR_PART_HANDLER_INFO_REPLACED
  - errPR_PART_HANDLER_NOT_FOUND
  - errPR_PART_KIND_NOT_FOUND
  - errPR_BUFFER_TOO_SMALL

Remarks This function creates an instance of the specified class using the specified DLL. The successful completion of this function depends on the information that is provided by the part-handler class. If the handler has already been registered, this function replaces the handler information.

### ODSetPreferredPartHandler

This function sets the preferred part-handler name.

Signature

    unsigned long ODSetPreferredPartHandler (ISOString isoPartKindName,
                                             ISOString isoPartHandleName)

Parameters

isoPartKindName (ISOString) - input

  The part kind name.

isoPartHandleName (ISOString) - input

  The part handler name.

Returns

rv (unsigned long) - returns

  Return codes.
  - NO_ERROR
  - ERROR_COULD_NOT_FIND_PART_KIND

### ODSetPreferredPartHandlerForCategory

This function sets the preferred part-handler to the specified name using the specified category.

Signature

    unsigned long ODSetPreferredPartHandlerForCategory (ISOString isoCategory,
                                                        ISOString isoPartHandlerName)

Parameters

isoCategory (ISOString) - input

  The category of the part.

isoPartHandlerName (ISOString) - output

  The part handler name.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR
  - ERROR_COULD_NOT_FIND_PART_KIND

### ODSetPreferredPartHandlerForFileExt

This function sets the preferred part-handler to the specified name using the specified file extension.

Signature

    unsigned long ODSetPreferredPartHandlerForFileExt (ISOString isoFileExt,
                                                       ISOString isoPartHandlerName)

Parameters

isoFileExt (ISOString) - input

  The file extension of the part.

isoPartHandlerName (ISOString) - output

  The part handler name.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR

### ODSetPreferredPartHandlerForFileType

This function sets the preferred part-handler to the specified name using the specified file type.

Signature

    unsigned long ODSetPreferredPartHandlerForFileType (ISOString isoFileType,
                                                        ISOString isoPartHandlerName)

Parameters

isoFileType (ISOString) - input

  The file type name.

isoPartHandlerName (ISOString) - output

  The part handler name.

Returns

rv (unsigned long) - returns

  Return code.
  - NO_ERROR

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]