Recommended usage of C++ API functions

Summary
The C++ API provides its own implementation of some functions. Below are the names and descriptions of the general API functions and examples of their use.

In this topic

The widget sets also have some other functions available that are not documented in this topic. For information on the widget-specific functions, see the help section for that widget set.

AoInitialize, AoUninitialize, and AoExit

  • AoInitialize—Used where CoInitialize would be used in COM programming. This function initializes ArcGIS Engine. The initialization must be done prior to ArcObjects being used and in addition to the use of the IAoInitialize interface, which handles licensing for the application. See the following code example:
[C++] 
extern "C" HRESULT AoInitialize(LPVOID pvReserved);
  • AoUninitialize—Used where CoUninitialize would be used in COM programming. This function uninitializes ArcGIS Engine. See the following code example:
[C++] 
extern "C" void AoUninitialize(void);
  • AoExit—used where exit would be used in non-ArcObjects code, as well as where return would be used in main. AoExit must be called before an application is exited. This allows portability to supported operating systems that require AoExit to correctly clean up various ArcGIS Engine elements. See the following code example:
[C++] 
extern "C" VOID AoExit(int number);
The following example illustrates how the three functions discussed above should be used within an application. Note that IAoInitialize must be scoped so that it will be out of scope before AoUninitialize is called. In this code, both AoInitialize and IAoInitialize are used. These are not the same thing: AoInitialize is the API call discussed above, while IAoInitialize is an ArcObjects interface used in licensing.
For the sake of simplicity the code snippets given don't always check HRESULTs, although as a developer you should always do so.
[C++] 
int main(int argc, char *argv[])
{
  // Initialize ArcGIS Engine and COM
  ::AoInitialize(NULL);

  // ArcGIS Engine licensing
  {
    IAoInitialize ipInit(CLSID_AoInitialize);
    esriLicenseStatus status;
    ipInit->Initialize(esriLicenseProductCodeEngine, &status);

    // ArcObjects Code here

    ipInit->Shutdown();
  }

  // Uninitialize ArcGIS Engine and COM
  ::AoUninitialize();

  // Exit the application
  AoExit(0);
}

AoCreateObject

  • AoCreateObject—used where CoCreateInstance would be used in COM programming. See the following code section: 
[C++] 
extern "C" HRESULT AoCreateObject(REFCLSID rclsid, LPUNKNOWN pUnkOuter, DWORD
  dwClsContext, REFIID riid, LPVOID *ppv);
When using smart pointers, this function will not be needed. However, you can create an instance of an object without smart pointers by using this function, as shown in the following code:
[C++] 
// Create a Workspace Factory without using smart pointers
IWorkspaceFactory *pWorkspaceFactory;
hr = ::AoCreateInstance(CLSID_ShapefileWorkspaceFactory, 0,
  CLSCTX_INPROC_SERVER, IID_IWorkspaceFactory, (void **) &pWorkspaceFactory);

AoAllocBSTR and AoFreeBSTR

AoAllocBSTR replaces SysAllocString. 

 
[C++] 
extern "C" BSTR AoAllocBSTR(const OLECHAR *sz);
  • AoFreeBSTR replaces SysFreeString.
[C++] 
extern "C" void AoFreeBSTR(BSTR bstr);
When using the smart type CComBSTR, the above two functions will not be needed. However, you can create and free BSTRs with them, as illustrated in the following example:
[C++] 
// display the feature type as "simple" or "other"
BSTR bsFeatureType;
esriFeatureType featType;
pFeatureClass->get_FeatureType(&featType);
switch (featType)
{
  case esriFTSimple:
    bsFeatureType = ::AoAllocBSTR(L "simple");
    break;
  default:
    bsFeatureType = ::AoAllocBSTR(L "other");
}

std::wcerr << L "Feature Type : " << (BSTR)bsFeatureType << std::endl;
::AoFreeBSTR(bsFeatureType);

AoToolbarAddCommand and AoToolbarAddTool

  • AoToolbarAddCommand replaces IToolbar->AddItem when adding a custom command. The custom command class must inherit from CAoCommandBase. See the following code example:

 
[C++] 
extern "C" HRESULT AoToolbarAddCommand(IToolbarControl *pToolbarControl,
  CAoCommandBase *commandBase, enum esriCommandStyles style);
  • AoToolbarAddTool replaces IToolbar->AddItem when adding a custom tool. The custom tool class must inherit from CAoToolBase. See the following code example:
[C++] 
extern "C" HRESULT AoToolbarAddTool(IToolbarControl *pToolbarControl,
  CAoToolBase *commandBase, enum esriCommandStyles style);
For examples on the use of AoToolbarAddCommand and AoToolbarAddTool, see How to create a custom command using AoBaseCommand and How to create a custom tool using AoBaseTool.