IUccCategoryContext.TryFindCategoryInstance Method

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Attempts to query a particular category instance belonging to this category context and matching a given container ID and an instance ID.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Function TryFindCategoryInstance ( _
    lContainerId As Integer, _
    lInstanceId As Integer, _
    <OutAttribute> ByRef ppCategoryInstance As IUccCategoryInstance _
) As Boolean

bool TryFindCategoryInstance (
    int lContainerId,
    int lInstanceId,
    out IUccCategoryInstance ppCategoryInstance
)

bool TryFindCategoryInstance (
    int lContainerId, 
    int lInstanceId, 
    [OutAttribute] IUccCategoryInstance^% ppCategoryInstance
)

boolean TryFindCategoryInstance (
    int lContainerId, 
    int lInstanceId, 
    /** @attribute OutAttribute() */ /** @ref */ IUccCategoryInstance ppCategoryInstance
)

Parameters

• lContainerId
  A value of the LONG (int, for a .NET application) type. This specifies the container ID.

• lInstanceId
  A value of the LONG (int, for a .NET application) type. This specifies the instance ID.

• ppCategoryInstance
  A value of the IUccCategoryInstance** (IUccCategoryInstance, for a .NET application) type. This yields the specified category instance of this category class for the given container if the category instance exists. Otherwise. this returns NULL.

Return Value

A value of the VARIANT_BOOL* (bool, for a .NET application) type. This returns TRUE if the specified category instance is found and FALSE if not.

Remarks

This method can be used to determine whether a particular category instance already exists in this category context. It returns TRUE together with the category instance if it exists. It returns FALSE along with NULL as a IUccCategoryInstance value if the specified category instance does exist in the category context.

Win32 COM/C++ Syntax

HRESULT TryFindCategoryInstance
(
   LONG lContainerId,
   LONG lInstanceId,
   IUccCategoryInstance** ppCategoryInstance,
   VARIANT_BOOL* pbFound
);

Note

In a Win32 application, the return value of a method or property is always an HRESULT value indicating the status of the call to the interface member. Any result of the operation is returned as a parameter marked with the [out, retval] attribute. In contrast, in a .NET application the HRESULT value indicating an error condition is returned as a COM exception and the [out, retval] parameter becomes the return value. For the UCC API-defined HRESULT values, see Trace and Handle Errors in Unified Communications Client API.

Example

The following example gets the category instance belonging to container 100 and whose instance Id is 1. The returned instance Value property of the returned instance is displayed on the local computer console.

This example uses the IUccCategoryContext returned in the illustrated event for clarity. A Unified Communications client should cache returned IUccCategoryContext objects. This local category cache should be updated as category context events are handled. A client that implements such a strategy can call TryFindCategoryInstances on the cached category context objects.

void _IUccCategoryContextEvents.OnCategoryInstanceAdded(
    IUccCategoryContext pCategoryCtx, 
    UccCategoryInstanceEvent pCategory)
{
   if (pCategoryCtx.get_CategoryInstances(100).Count > 0)
   {
      IUccCategoryInstance i;
      if (pCategoryCtx.TryFindCategoryInstance(100, 1, out i))
      {
         if (i.Value != null)
         {
            Console.WriteLine("Context:" +
               i.CategoryContext.Name +
               " Value:" +
               i.Value.ToString() +
               " Instance Id:" +
               i.InstanceId.ToString());
         }
      }
   }
}

Thread Safety

All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2000 with Service Pack 4, Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms

See Also

Reference

IUccCategoryContext Interface
IUccCategoryContext Members
Microsoft.Office.Interop.UccApi Namespace