How to Use the Activation Context API

how-to | home

If you have not read When to Use the Activation Context API you may wish to read it first.

Activation context lifetime

An activation context is first created using CreateActCtx(), then it may be activated and deactivated multiple times using ActivateActCtx() and DeactivateActCtx(). Finally it is destroyed using ReleaseActCtx().

It is important to remember that the activation contexts must be deactivated in the reverse order of activation.

Additionally, keep in mind that the operating system keeps a reference count for each activation context and only destroys the context when the reference count reaches zero. CreateActCtx sets the reference count to 1, ActivateActCtx() and AddRefActCtx() increment the reference count and both DeactivateActCtx() and ReleaseActCtx() decrement the reference count.

Example code snippet: C/C++

  ACTCTX actctx = {sizeof(actctx)};
  actctx.lpSource = L"Lifetime.Example.Manifest";
  HANDLE hActCtx = CreateActCtx(&actctx);
  
  ULONG_PTR cookie = 0;
  BOOL fOK = ActivateActCtx(hActCtx, &cookie);
  
  sampleDLL::IsxsSampleControl *pControl = NULL;
  HRESULT hr = CoCreateInstance(__uuidof(sampleDLL::CsxsSampleControl), NULL, CLSCTX_INPROC_SERVER, __uuidof(sampleDLL::IsxsSampleControl), (void**)&pControl);
  
  DeactivateActCtx(0, cookie);
  ReleaseActCtx(hActCtx);

This code is copied from the example project "Examples\ActCtx\Lifetime_cpp". Note that all error checking has been removed to simplify the example.

The first three lines of code create the activation context using manifest "Lifetime.Example.Manifest". The following lines activate this context, create the requested COM object then deactivate and release the activation context. As soon as the COM object is created the activation context is not needed any more to use this object. This example first deactivates and destroys the activation context and only then it starts using the just created COM object.

Example code snippet C#

  ACTCTX info = new ACTCTX();
  info.cbSize = Marshal.SizeOf(typeof(ACTCTX));
  info.lpSource = "Lifetime.Example.Manifest";
  IntPtr hActCtx = CreateActCtx(ref info);

  IntPtr cookie = IntPtr.Zero;
  bool bOK = ActivateActCtx(hActCtx, out cookie);

  IsxsSampleControl sample = new CsxsSampleControl();

  string str = sample.VersionString;
  Console.WriteLine("VersionString = {0}", str);
  
  DeactivateActCtx(0, cookie);
  cookie = IntPtr.Zero;

  ReleaseActCtx(hActCtx);
  hActCtx = IntPtr.Zero;

This code is copied from the example project "Examples\ActCtx\Lifetime_cs". Note that all error checking has been removed to simplify the example. Also all the necessary declarations of the Windows APIs are not included in the above code but are a part of the example included with Manifest Maker.

The first four lines of code create the activation context using manifest "Lifetime.Example.Manifest". The following lines activate this context, create the requested COM object. Note that unlike in the C++ example above, we cannot deactivate the activation context yet. COM Interop will need the context to locate the type library necessary to make the COM object call. Only after we are done using the object, can we  deactivate and release the activation context.

More information