Difference between revisions of "Uno/Binary/Spec/Environment Descriptor"

Revision as of 08:55, 18 April 2006

author: Kr
version: 8174
state: draft
created: 08/07/2005
type: specification

Binary UNO

Purpose Environments

Feature

This feature extends the environment type naming by introducing a so called "purpose" part into the environment type naming, basically changing the environment type name to become an environment descriptor, defining the environment type and the environment purpose.

(Purpose) Environments are descripable as

<env-name>[:<purpose-name>]*

meaning that purpose names can be chained. This allows to have different environments of the same types to be globally visible, while differing in their purpose. For example:

• "uno:thread"
• "uno:debug"
• "uno:log:thread"
• "gcc3:debug"
• "gcc3"

When requesting the above examples, every environment is globally visible, while partly representing the same type or purpose, every combination is unique. The former string describing environment type names becomes an environment descriptor.

Rationale

Currently every UNO environment is either annonymous or globally visible. All globally visible environments are uniquely identified by the type name. That means, that every bridge specific environment can only be visible once globally. To be able to use more than one type specific environment in a global way, support for a differentiator (the purpose) is needed.

API

Bin-UNO - uno/EnvDcp.h:

void uno_EnvDcp_getTypeName(rtl_uString const * envDcp, rtl_uString ** pTypeName);

void uno_EnvDcp_getPurpose (rtl_uString const * envDcp, rtl_uString ** pPurpose);

CPP-UNO - cppu/EnvDcp.hxx:

rtl::OUString cppu::EnvDcp_getTypeName(rtl::OUString const & envDcp);

rtl::OUString cppu::EnvDcp_getPurpose (rtl::OUString const & envDcp);

Note: All access to members of environment descriptors should be changed to use the above access functions.

Compatibility Issues

The character ':' gets a special meaning in all environment type names. All Binary UNO runtime functions dealing with environments typenames

uno_getEnvironment

uno_getRegisteredEnvironments

uno_createEnvironment

uno_dumpEnvironmentByName

are changed to support purposes parts. All parameter names get changed to reflect the new semantics of the former type name. The "pTypeName" member of the UNO environment does not get changed, to ensure build compatibility.

In case of not providing purposes in an environment descriptor, the env. descriptor degenerates to just an environment type name. This means, that the change is compatible with all former usages and bridges, in case it does not get utilized. To utilize this feature, bridges should use the appropriate accessor methods, to get the type or purpose name from the environment descriptor.

Note: Purpose environments _must_ not be used with not purpose environment aware language bridges.

Dependencies

None.