CPMI (Check Point Management Inter- face) API...

OPSEC

CPMI (Check Point Management Inter-

face) API Specification

OPSEC SDK 6.0

© 2003-2006 Check Point Software Technologies Ltd.

All rights reserved. This product and related documentation are protected by copyright and distributed under licensing restricting their use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form or by any means without prior written authorization of Check Point. While every precaution has been taken in the preparation of this book, Check Point assumes no responsibility for errors or omissions. This publication and features described herein are subject to change without notice.

RESTRICTED RIGHTS LEGEND:

Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR 52.227-19.

TRADEMARKS:

©2003-2006 Check Point Software Technologies Ltd. All rights reserved.

Check Point, Application Intelligence, Check Point Express, the Check Point logo, AlertAdvisor, ClusterXL, Cooperative Enforcement, ConnectControl, Connectra, CoSa, Cooperative Security Alliance, Eventia, Eventia Analyzer, FireWall-1, FireWall-1 GX, FireWall-1 SecureServer, FloodGate-1, Hacker ID, IMsecure, INSPECT, INSPECT XL, Integrity, InterSpect, IQ Engine, Open Security Extension, OPSEC, Policy Lifecycle Management, Provider-1, Safe@Home, Safe@Office, SecureClient, SecureKnowledge, SecurePlatform, SecuRemote, SecureXL Turbocard, SecureServer, SecureUpdate, SecureXL, SiteManager-1, SmartCenter, SmartCenter Pro, Smarter Security, SmartDashboard, SmartDefense, SmartLSM, SmartMap, SmartUpdate, SmartView, SmartView Monitor, SmartView Reporter, SmartView Status, SmartViewTracker, SofaWare, SSL Network Extender, Stateful Clustering, TrueVector, Turbocard, UAM, User-to-Address Mapping, UserAuthority, VPN-1, VPN-1 Accelerator Card, VPN-1 Edge, VPN-1 Pro, VPN-1 SecureClient, VPN-1 SecuRemote, VPN-1 SecureServer, VPN-1 VSX, VPN-1 XL, Web Intelligence, ZoneAlarm, ZoneAlarm Pro, Zone Labs, and the Zone Labs logo, are trademarks or registered trademarks of Check Point Software Technologies Ltd. or its affiliates. All other product names mentioned herein are trademarks or registered trademarks of their respective owners. The products described in this document are protected by U.S. Patent No. 5,606,668, 5,835,726, 6,496,935 and 6,850,943 and may be protected by other U.S. Patents, foreign patents, or pending applications.

For third party notices, see “THIRD PARTY TRADEMARKS AND COPYRIGHTS” on page 135.

Table of Contents 5

Contents

Preface Who Should Use This Guide................................................................................ 8Summary of Contents ......................................................................................... 9

Appendices .................................................................................................. 9What Typographic Variations Mean .................................................................... 10

Chapter 1 Introduction Overview ......................................................................................................... 14

Compatability ............................................................................................. 14Object Repository Components.......................................................................... 15

Fields ........................................................................................................ 17Objects ...................................................................................................... 19Containers.................................................................................................. 22Tables ....................................................................................................... 23

The CPMI Application ...................................................................................... 27Programming Model ......................................................................................... 30

Threads ..................................................................................................... 31CPMI API Overview .......................................................................................... 32

Application Objects..................................................................................... 32Naming Conventions ................................................................................... 33Function Return Values ............................................................................... 34Error Handling............................................................................................ 34Memory Management .................................................................................. 35Establishing a CPMI Session........................................................................ 35Partial Object Retrieval................................................................................ 39Object Referencing ..................................................................................... 41Object Uniqueness...................................................................................... 42Notification ................................................................................................ 43Locking Objects.......................................................................................... 44Caching ..................................................................................................... 45Queries ...................................................................................................... 45Object Status Monitoring ............................................................................. 47Auditing..................................................................................................... 47Iteration..................................................................................................... 48Event Handling........................................................................................... 49Fields data type mapping............................................................................. 51

Chapter 2 Schema Overview ......................................................................................................... 54Details............................................................................................................ 55

Special Schemes ........................................................................................ 58

6

Chapter 3 API Functions Function Calls ................................................................................................. 60

Memory Allocation ...................................................................................... 61CPMI General Utilities................................................................................. 64CPMI Sessions and Connections................................................................... 67CPMI Requests........................................................................................... 73Databases .................................................................................................. 80Tables ....................................................................................................... 99Objects .................................................................................................... 106Contexts .................................................................................................. 134Applications ............................................................................................. 139Classes in a Schema ................................................................................. 147Reference, Iteration and ID of Objects ........................................................ 156Elements ................................................................................................. 165Fields ...................................................................................................... 179Errors ...................................................................................................... 192Event Registration and Notification ............................................................ 195

Event Handlers.............................................................................................. 204Operation ID............................................................................................. 204CPMIBind_CB .......................................................................................... 204CPMICertificate_CB .................................................................................. 205CPMIObj_CB ............................................................................................ 206CPMINotify_CB ........................................................................................ 207CPMIDb_CB ............................................................................................. 208CPMIQuery_CB......................................................................................... 209CPMILicense_CB ...................................................................................... 210

Error Codes ................................................................................................... 212

Appendix A CPMIClientDataTypes.h Data Type

Index.......................................................................................................... 227

7

Preface PPreface

In This Chapter

Who Should Use This Guide page 8

Summary of Contents page 9

What Typographic Variations Mean page 10

Who Should Use This Guide

8

Who Should Use This GuideThis document describes the CPMI (Check Point Management Interface) API Specification.

This API specification is written for developers who write software to enhance the network security provided by VPN-1.

It assumes that you have read the Check Point OPSEC API Specification.

It also assumes that you have a basic understanding and a working knowledge of the following:

• system and network security

• the VPN-1 product

• system and network administration

• the C and/or C++ programming language

• the Unix or Windows operating system

• Internet protocols.

Summary of Contents

Preface 9

Summary of ContentsThis guide contains the following chapters:

AppendicesThis guide contains the following appendices

Chapter Description

Chapter 1, “Introduction” This chapter provides an introductions to the CPMI (Check Point Management Interface) API Specification which provides a secure interface for accessing the Check Point object repository.

Chapter 2, “Schema” This chapter explains how CPMI API is based upon clear object definition. The chapter describes these definitions in a set of schema files.

Chapter 3, “API Functions” This chapter describes the functions provided by the OPSEC CPMI API.

Appendix Description

Appendix A, “CPMIClientDataTypes.h Data Type”

Provides the CPMIClientDataTypes.h data type

What Typographic Variations Mean

10

What Typographic Variations MeanThe following table describes the typographic variations used in this book.

TABLE P-1 Typographic Conventions

Typeface or Symbol Meaning Example

AaBbCc123 The names of commands, files, and directories; on-screen computer output; code

Edit your .login file.Use ls -a to list all files.machine_name% You have mail.session = sam_new_session (client, server);

AaBbCc123 same as above, but with emphasis

session = sam_new_session (client, server);

Save Text that appears on an object in a window

Click on the Save button.

<your text> Replace the angle brackets and the text they contain with your text.

Edit the file <FWDIR>\lib\yourfile.xx

.

.

.

Lines of data or code omitted from example

line 1line 2...line n


Preface 11

[item] The item is optional.

dir [/o]

[item1] ... [item2] List of optional items

dir [/o] [/w] [/s]

item1 | item2 | item3 Choose one of the items.

copy infile1 | infile1 + infile2 |infile1 + infile2 + infile3 outfile

italic Specific values will be shown in italics

one of addnet | addapp

TABLE P-1 Typographic Conventions(continued)

Typeface or Symbol Meaning Example


12

13

Chapter 1Introduction

In This Chapter

Overview page 14

Programming Model page 30

Object Repository Components page 15

The CPMI Application page 27

CPMI API Overview page 32

Overview

14

OverviewCheck Point’s OPSEC (Open Platform for Security) integrates and manages all aspects of network security through an open, extensible management framework. Third party security applications can plug into the OPSEC framework via published application programming interfaces (APIs). Once integrated into the OPSEC framework, all applications can be configured and managed from a central point, utilizing a single Security Policy editor.

This document describes the CPMI (Check Point Management Interface) API Specification which provides a secure interface for accessing the Check Point object repository.

CPMI Supports an asynchronous development model, aiming at unified access for internal and external third-party application development in the following four categories:

• authentication

• database manipulation

• object manipulation

• application manipulation

CompatabilityCPMI connections are not backward compatible. This means, for example, that a CPMI application which uses OPSEC SDK 6.0 cannot communicate with any version of VPN-1 prior to NGX R60.

However, CPMI connections are forward compatible. This means, for example, that a CPMI application which uses NG FP3 OPSEC SDK can communicate with VPN-1 NGX R60.

Object Repository Components

Chapter 1 Introduction 15

Object Repository ComponentsThe objects in the Check Point repository are defined in Object Definition Files, or schema files. A schema is comprised of one or more classes noting its type. Each class includes one or more fields, or attributes. The schema specifies the type of data that may be stored in each field (e.g. ASCII text, long integers, etc.). For a detailed listing of the schema see page 55.

In other words, every Check Point object belongs to a schema class, and may only contain the type of data specified by that class.

An object is an instance of a schema class definition, comprising a set of attributes appearing as the fields of the object. Each field is of specific type and may hold specific data (valid values). On creation of such an instance, each field will contain a default value as defined by the schema files.

There is no partial definition of an object, and each time an object is created, it will hold the full set of attributes associated with it as defined for the object.

In the Check Point Repository, objects are organized in hierarchical order, as illustrated in Figure 1-1 below.

Object Repository Components

16

Figure 1-1 object repository hierarchy

In other words, the Check Point object repository may contain one or more databases.

Each database contains a set of tables. Each table in the database contains objects of the same type.

Objects may represent applications or contain status information for monitoring purposes. Each object is comprised of one or more fields, according to the schema class to which it belongs. Status objects are automatically generated objects and are therefore special. Application objects should be treated just as any other object, though once you have obtained the Application Object Handle an additional set of behavior is available for the application. For more information, see “Application Objects” on page 32 and “Object Status Monitoring” on page 47.

Table

Object

Application Object

Status Object

Class

Container

Ordered Container

Field

Session

Error

Iteration

Result

Reference

Notification

Fields


Depending on the field type and definitions, fields may be organized in containers or in ordered containers. Containers are associated with fields holding multiple values, ordered and non-ordered. For more information, see “Containers” on page 22.

The CPMI API enables iteration over each component in the objects repository. For example iteration can occur through all the tables in a database, through all the objects in a table, through the fields of an object or through the objects in a result set of a query. The CPMI API also enables you to manage objects according to their schema definitions (according to schema class).

In the following pages, each of these components is examined more closely, using a bottom-up approach. To go directly to a specific component, consult Table 1-1 below.

FieldsA field contains three types of information:

• the data specific to an object

• attributes that determine the values valid for that field

• attributes that determine the default value for that field

Each field has a type. This type determines how values are stored and retrieved from objects. Possible field types include:

• strings

• numbers

• booleans

• owned object - Represent another object which belong to current object and has no self existence. For example, an interface definition of a gateway object.

• member object - Reference to another actual object. When this object is deleted the reference is cancelled. For example, a user member in a group.

Table 1-1 CPMI components

For more information about this CPMI component.... See...

Fields page 17

Objects page 19

Containers page 22

Tables page 23

Fields

18

• linked object - Reference to another actual object. This object can not be deleted until the referencing field is not cancelled. For example, a source field in a rule object.

For more information about object based field types, see “Objects” on page 19.

Field Type DefinitionAll field types are predefined and are loaded into memory upon CPMI server initialization. The schema syntax definition is internal to Check Point and is only being used for internal system purposes.

Each field type has the following attributes:

Sample Field DefinitionFigure 1-2 provides an example of a basic field definition of boolean.

Warning - No changes are allowed to any of the schema definitions. Any modifications to the schema definitions may result in unexpected behavior.

Table 1-2 field type attributes in Field Type file

Attribute Description

name A unique name that will be used in the classes definition to associate a field with a class.

type The field’s data type.

defvalue The default value for this field, if any. The value is set as the field value on instantiation of the object.

validvalues A list or range of values indicating the set of valid values for the field. Validation of the object will succeed if the value assigned to the field belongs to the list or range of field valid values.

multiple Indication of whether the field may have more than one value.

ordered Indication of the multiple characteristics of the field. If the field can have more than one value, these values must be ordered.

Objects


Figure 1-2 sample field definition

The name of this field is boolean. This field is of boolean type, with a default value of false. Valid values can either be true or false.

ObjectsAll objects are predefined and are loaded into memory upon CPMI server initialization. Objects are comprised of one or more fields. Each object’s field has the following attributes:

:(boo lean :type (boo lean) :de fva lue (fa lse ) :va lidva lues ({true ,fa lse}))

Note - For actual usage and mapping of schema defined fields to ‘C’ data types see “Fields data type mapping” on page 51 and sample code under #6 and #7 of “The CPMI Application” on page 27 and the Schema Chapter beginning on page 54..

Table 1-3 field type attributes in Object Definition File


field name The name of the field. This attribute may be empty if the object is a group member. If the field is multiple, the field name may follow one of two naming schemes:• all values have the same name• all values are indexed (for example, interface1,

interface2, etc.)

field type One of the field types defined in the Field Definition Schema (see page 55).

Objects

20

In addition, each object may have the following object level attributes:

Object Class InheritanceIn order to make the Object Definition File more compact, easier to maintain and improve readability any class may inherit the attributes of another class. This enables the definition of base classes. CPMI supports multiple levels of inheritance. All fields defined for the base class are automatically defined for the inheriting class as well. Field values are inherited unless specifically overwritten.

As a consequence of object class inheritance, a class may be abstract. An abstract class cannot be instantiated and must always be included as part of another class.

multiple The field may have multiple values indicated by the letter “M” or the letter “O” where “M” denotes a list of values and “O” represents an ordered list of values. (see page 55)

validvalues A list or range of values indicating valid values for the field. A field passes the validation process only if it has a value assigned from the valid value list. If defined in the Object Type Definition File, these values override those values defined in the Field Type Schema Definition.

defvalue The default value associated with the field on object instantiation.

Table 1-4 object level attributes in Object Definition File


owned Appears only if an object is an owned object.

validfunc A function to be called in order to validate the object.

baseobj The base class for this object. See “Object Class Inheritance”” below.

Table 1-3 field type attributes in Object Definition File(continued)


Note - Inheritance semantics here is slightly different from C++ inheritance, in this case it refers to data only.

Objects


Object ClassificationObject classification is often not as straightforward as it might seem. For example, if objects are classified according to their type, the classification scheme may fail in the following situations:

• Some objects do not have type field. Their type are usually derived from their context.

For example, in the rule object, the column source is an non-typed object. The different software modules know that source is a group of network objects because of its context.

• In some objects, the type may be generic.

For example, the type group is used to describe groups of different elements, regardless of the element types. Sometimes it may be necessary to differentiate between groups of network objects and groups of services.

• Classification based on type may lead to dependency on fields. For example, a Bay Networks router and a Cisco router share the same type (router). However, there may be many fields that are relevant only to Cisco routers and not to Bay routers. Moreover, the valid values of some of the common fields may be different for each vendor.

There are several solutions to this problem:

• Classification can be done on-the-fly, by computing a value for an object’s class attribute when the object is retrieved from the database.

• Each class can be defined using a query phrase (e.g. “type = 'router' & vendor = 'cisco'”). If the object matches the query phrase, the object is classified accordingly.

This is the query string object level attribute.

Note that an object's class, as opposed to an object’s type, can be modified.

Containers

22

ContainersAs their name implies, containers contain other elements (numbers, strings, addition field types).

Containers are generated automatically according to the definitions in the schema files. Containers cannot be created explicitly by calling a specific API function.

There are two types of containers:

• Containers are generated for each field type that allows multiple values (that is, the “multiple” attribute is TRUE).

• Ordered containers are generated for each field type that allows ordered multiple values (that is, the “ordered” attribute is TRUE).

Table 1-5 is an excerpt from the object schema definitions of the OSE device object in the network object table.

The M/O column stands for “multiple” and/or “ordered”.

Table 1-5 Excerpted Object Schema Definitions

Class OSE_device (table network_objects)

name type valid values default value

M/O

SNMP owned_object SNMP, NULL SNMP

color string black

comments string

edges linked_object ambiguous network, provisory network, network

M

exportable boolean

interfaces owned_object O

ipaddr string

location string

operating_system

owned_object operating system operating system

Tables


The “edges” field is of type “linked object” and may contain multiple objects of type as specified in the valid values column. This is noted by the “M” in the M/O column. The interfaces field is of “owned object” type and may hold multiple values but in an ordered manner, denoted by an “O” in the M/O column.

Coding Sample:

The sample iterates over a container identified by its HCPMICNTR Handle and fetches the content of a field elemValue. Moving to the next element in the Container is done by calling to CPMIIterCntrGetNext. To check whether we did not reach the end of the Container call CPMIIterCntrIsDone and check its return value to be CP_S_FALSE.

TablesThe following tables are defined in the Object Type Definition Module. All table permissions are read / write, unless stated otherwise.

HCPMICNTR hCntr=...HCPMIITERCNTR iterCntr;

CPMICntrIterElements (hCntr, &iterCntr);while (CP_S_FALSE == CPMIterCntrIsDone (iterCntr)){ tCPMI_FIELD_VALUE elemValue; CPMIIterCntrGetNext (iterCntr, &elemValue); ........CPMIReleaseFieldValue (&elemValue); } CPMIHandleRelease (iterCntr);}

Table 1-6 database tables

This table... includes... Access

network_objects network objects (e.g. network_object)

services services objects (e.g. tcp_service, udp_service)

resources resources objects (e.g. ftp_resources)

resources_types resource types table R/O

Tables

24

servers Server objects (e.g. radius_server, tacacs_server)

times time objects (e.g. time, scheduled_event)

users users and user groups (e.g. user, user_group)

keys encryption keys (e.g. SKIP_DH_key)

tracks contain objects used in the "Track" column in the SmartDashboard

R/O

protocols contain groups of services according to their type

R/O

userdefaults contains user default templates R/O

Table 1-7 admin tables


administrators administrator definitions

gui_clients GUI clients

licenses license management

packages SmartUpdate packages

Table 1-8 policies tables

Table Name includes... Access

fw_policies VPN/FireWall policies

fg_policies FloodGate policies

slp_policies SecureClient policies

ce_policies Consolidation Engine policies

Table 1-9 properties tables


properties properties

ce_properties Consolidation Engine properties

Table 1-6 database tables(continued)


Tables


ClassesA table holds objects that are encapsulated into a common category and may include objects of more than one class. A class is a common field structure for part of the objects related to a table. For example in Table 1-15 refer to services, the objects in this table may relate to one of the following classes:

Table 1-10 encryption tables


encryption encryption definitions

Table 1-11 miscellaneous tables

This table... Includes... Access

setup

qos Quality of Service definitions

rtm SmartView Monitor definitions

securemote SecuRemote definitions

svn Secure Virtual Network definitions

Table 1-12 external database tables


ldap LDAP (Light Directory Access Protocol) definitions

Table 1-13 applications tables


applications application objects definitions

statuses status objects definitions R/O

graph objects SmartMap objects definitions

Table 1-14 OPSEC tables


opsec contains OPSEC applications, CVP and UFP collections

products contains OPSEC products

Tables

26

Table 1-15 TABLE 1-5 Services Classes Example

Class...compound_tcp_servicedcerpc_service icmp_serviceother_servicerpc_serviceservice_grouptcp_serviceudp_service

Note - Each class includes the relevant fields for this type of service. For example the port field will appear in tcp_service but not in icmp_service, since it is irrelevant there.

The CPMI Application


The CPMI ApplicationThis section describes the development flow of a basic CPMI Client application.

Logic elements may be included as required but the flow must begin with these three essential steps before the rest of the application flow can be established:

1. Establish Client/Server Session

2. Authenticate the Session

3. Open Database

Once the database is open, all CPMI APIs can be utilized in order to implement application requirements.

Just before exiting from the application, the database must be closed to complete the CPMI logic.

The full scope of the application flow is as follows:

1. Establish a session between the CPMI Server and the Client application as follows:

a. Call opsec_init to create the OPSEC environment.

b. Call opsec_init_entity with CPMI Server parameters to create the Server entity. (For a complete list of the relevant callbacks see the opsec_init_entity type values table in the Overview of the OPSEC API Specification.)

c. Call opsec_init_entity with the CPMI Client parameters to create the Client entity.

d. Call CPMISessionNew (see page 67) with the CPMI Client and Server entities, as well as the desired connection time-out. Successful completion returns the OpsecSession structure specific to this session.

2. Authenticate the session using CPMISessionBind (see page 69). For certificate based binding (see page 68) or CPMISessionBindUser for user based bind (User Name & Password) (see page 68).

3. Open the database using CPMIDbOpen (see page 81).

The database may be opened in Read-Only mode or Read/Write mode.

Note - The timeout arguement is valid for all operations on the created session, not just the connection.


28

The database handle returned by this function is required for the following steps.

4. Create, retrieve, delete or reduce objects from the database as follows:

• To create an object, call CPMIDbCreateObject (see page 115).

The new object has the attributes and default values specified in the Object Definition File. Note that creating an object does not automatically save the object into the database. This takes place only after a call to CPMIObjUpdate (see page 117).

• To modify an existing object, retrieve the handle to the table containing the object by calling CPMIDbGetTable (see page 99) with the table’s name as one of the arguments.

Alternately, iterate over all the tables in the databases by calling CPMIDbIterTables (see page 102), and by using the iteration functions (see “Iteration” on page 48).

After obtaining the table handle, retrieve the object using CPMITblGetObj (see page 107).

• To delete an object one can use either of the following API calls:

CPMITblDeleteObj(see page 108) deletes an object from the database identified by its table handle and object’s name (Table level manipulation).

CPMIObjDelete (see page 116) deletes an object from the database identified by its object handle (Object level manipulation).

• To check and see if the object is currently reduced due to context reduction use the following API call CPMIObjIsReduced (see page 109) checks if the object is currently reduced due to context reduction.

5. Iterate over the object’s fields as follows:

1. Retrieve the handle to the object’s class by calling CPMIObjGetClass (see page 127).

2. Retrieve a field iteration handle by calling CPMIClassIterFields (see page 189).

3. Iterate over the fields by calling CPMIIterFldGetNext (see page 190).

4. Use utility functions such as CPMIFldGetName (see page 185) and CPMIFldGetType (see page 185) to retrieve the field’s name and type respectively.

6. Set a field value as follows:



Call CPMIObjSetFieldValue (see page 180) and CPMIObjSetFieldValueByName (see page 180) to set a field value by specifying the field’s handle or the field’s name respectively.

A field’s value is set using the tCPMI_FIELD_VALUE structure. This structure has two fields:

• fvt - an enumerated type describing the type of value

• bFv - the field’s value

bFv is a union type and may be any valid CPMI field type.

The following code fragment sets a Boolean field (field_name) to TRUE: Value type must be set, followed by the actual field value:

7. Retrieve a field value as follows:

Call CPMIObjGetFieldValue (see page 183) and CPMIObjGetFieldValueByName (see page 184) to retrieve a field value by specifying the field’s handle or the field’s name respectively.

The following code fragment retrieves the value of a field.

Now fv.fvt is the type of the field we got back and fv.bFv is the actual value.

8. Save the modified object to the database by calling CPMIObjUpdate (see page 117).

9. Close the database by calling CPMIDbClose (see page 81) using the handle returned by the corresponding call to CPMIDbOpen in step 3 on page 27.

tCPMI_FIELD_VALUE fv;fv.fvt = eCPMI_FVT_BOOL;fv.bFv = TRUE;CPMIObjSetFieldValueByName (hSomeObj, "field_name", &fv);

CPMI_FIELD_VALUE fv;CPMIObjGetFieldValueByName (hSomeObj, "field_name", &fv);

Programming Model

30

Programming ModelThe usual way to access and manipulate Check Point objects repository is through one of the Check Point Graphic User Interfaces:

• the Windows GUI (described in [1])

• the X/Motif GUI, functionally identical to the Windows GUI

CPMI (Check Point Management Interface) provides an access API into the Check Point object repository located on the Check Point SmartCenter Server while maintaining its integrity. All Check Point clients (the SmartCenter Server, SmartView Tracker, etc.) use CPMI similarly.

CPMI enables third-party applications to use the following Check Point management services:

• Authentication (user name / password, certificate based)

• Database manipulation, including:

• A database locking mechanism

• Database Read and Write capabilities

• Database queries

• Database monitoring and version control

• Logging of all changes to database

• Administrator auditing

• Object manipulation, including:

• Creating new objects

• Assigning objects unique IDs

• Updating existing objects

• Deleting objects

• Object version control (modification information)

• Validating objects and object fields

• Application manipulation, including:

• Installing and uninstalling Security Policies

• Creating and pushing certificates

• Retrieving the status of an application

Threads


• License management

• A notification mechanism that enables tracking and responding to specified events.

ThreadsCPMI API is not Thread-Safe. Only one thread may use CPMI API at a time. For more information see “Multithread OPSEC Applications” in the Check Point OPSEC API Specification

CPMI API Overview

32

CPMI API OverviewThis section provides a general overview of the CPMI API and will emphasize the basics required to understand the API itself, such as the API naming convention, parameters, return values and error handling. More advanced topics will be clarified such as Establishing CPMI Session, Notification mechanism, Object Locking, Application Objects, Status Monitoring and more.

Application ObjectsUnlike other objects, application objects are more than a set of fields, they carry additional or extended functionality and are able to carry out functions such as handling certificates, license management and installing or uninstalling Security Policies.

Application objects are contained in the application object table (‘application’). When an application object is retrieved from the application object table, it is identified by its object handle, HCPMIOBJ.

To enable an application object’s specific behavior, its object type must be extended. This is done by calling CPMIObjGetAppHandle (see page 139). CPMIObjGetAppHandle retrieves the application handle (HCPMIAPP) associated with the application object, therefore any extended functionality available to the object can take place.

The following functions manage application objects:

Table 1-16 application management functions

function name description See ...

CPMIDbGetAppsStatus retrieves the status of the application page 146

CPMIAppGetObject retrieves the HCPMIOBJ handle associated with application

page 140

CPMIDbQueryApps queries the database for all applications of a specified type

page 140

CPMIAppCreateCertificate creates a new certificate - a password is required - and possibly pushes it

page 141

CPMIAppPushCertificate pushes a certificate that has already been created

page 142

Naming Conventions


CPMIDbGetAppsStatus is a database category API function which can take a single or a list of application objects as a parameter to retrieve status information.

Licensing CPMI API is available to support the improved licensing mechanism of Check Point. For details see the SmartUpdate documentation.

Note the following:

• Like any other objects, application objects can be registered for event notification (“Notification” on page 43).

• To test whether an object is an application object, use CPMIObjIsOfClass (see page 127) to determine whether the object is derived from the application base class, or use CPMIObjGetAppHandle (see page 139)

• External firewalls are not considered to be application objects.

• The SmartCenter Server is considered to be an application object which can be monitored and a support database can be installed.

Naming ConventionsCPMI API function names have three parts, as follows:

• The CPMI prefix

• The context of operation - Db (for database), Tbl (for table), Obj (for object), etc.

• The operation itself - Open, GetObj, GetName etc.

Consider the following examples:

• CPMIDbOpen - opens a database (see page 81)

• CPMITblGetObj - retrieves an object from a table (see page 107)

• CPMIObjValidate - validates an object. (see page 121)

CPMIAppRevokeCertificate revokes a certificate that has not been pushed

page 143

CPMIAppAttachLicense associate a licence object with an application

page 144

CPMIAppDetachLicense revert the association (detach) from an application

page 145

Table 1-16 application management functions(continued)


Function Return Values

34

Function Return ValuesAlmost all CPMI functions return a status code of type cpresult. cpresult is a 32 bit value as follows:

On success, most CPMI functions return CP_S_OK. Error codes are always less than zero.

Error HandlingThe success or failure of a function can be determined using the CP_FAILED and CP_SUCCEEDED macros defined in cpresult.h .

For example, consider the following code fragment:

Table 1-17 cpresult fields and meaning

field bits (bit 0

least

significant)

size meaning

severity 31 1 0 = success1 = error

facility 16-30 15 the status code group to which this belongsCheck Point reserves the right to define any facility codes.

code 0-15 16 a code indicating the function results (on success or error)

cpresult ret = CPMIDbOpen (pSession, szDatabase,…);if ( CP_FAILED(ret) ) { const char * msg = CPGetErrorMessage (ret); printf ("Open Database Failed: %s\n", msg); return ret; }

Note - After each CPMI function call, it is crucial that you check whether the function was successful in order to handle the application behavior properly.

Memory Management


On failure, the return code mechanism for a function call is associated with a descriptive error message. The following functions retrieve these error messages:

Memory ManagementTo avoid memory leaks, CPMI provides the following functions for memory management:

Establishing a CPMI SessionCPMISessionNew (see page 67) initializes the OPSEC CPMI session.

The steps for establishing an OPSEC session between the CPMI Server and the Client application:

Establish a session between the CPMI Server and the Client application as follows:

1. Call opsec_init to create the OPSEC environment.

2. Call opsec_init_entity with CPMI Server parameters to create the Server entity.

Table 1-18 error handling functions


CPGetErrorMessage Retrieves the error message associated with cpresult.

page 212

Table 1-19 memory management functions


CPMIFreeString frees the strings allocated by the CPMI API page 61

CPMIHandleAddRef increments the handle reference count - use this function every time you make a copy of a CPMI handle since other functions that also have copies may call CPMIHandleRelease while your copy is still valid

page 61

CPMIHandleRelease decrements the handle reference count - use this function to release the CPMI handles allocated in various API functions

page 62

Establishing a CPMI Session

36

3. Call opsec_init_entity with the CPMI Client parameters to create the Client entity.

4. Call CPMISessionNew (see page 67) with the CPMI Client and Server entities, as well as the desired connection time-out. Successful completion returns the OpsecSession structure specific to this session.

For a complete development flow sample see Figure 1-4 on page 37.

Once the session is established, the CPMI Client must authenticate itself and bind the connections. This may be done in one of the following ways:

• By providing the User Name and Password

• By providing a certificate (see “Managing Certificates for an Application” on page 141).

The functions that manage the CPMI session are listed below:

There are two methods of establishing a Client/Server session and the required initial definitions:

The first is to use an Administrator User Name and Password:

Initial Definitions:

1. Define the administrator and password via cpconfig.

2. Define the administrator database permissions via cpconfig.

3. Define the machine on which the client will be activated via cpconfig by adding the machine name or IP address to the allowed SMART Clients list.

For further information on cpconfig see Chapter 1 of the VPN-1 Reference Guide.

The following code sample is an example of implementation for user based bind:

Table 1-20 CPMI session management functions


CPMISessionNew creates a new OPSEC session for CPMI page 67

CPMISessionBindUser binds using a name and password page 68

CPMISessionBind uses the information used to create the OpsecSession and OpsecEntity to bind. This API is used to bind using a certificate that was declared in the opsec_init_entity and CPMISessionNew stages.

page 69



Figure 1-3 A. Callback Definitions

Note - The call for CPMISessionBindUser in the callback definition of EstablishHandlerCB.

Figure 1-4 B. Establishing the Session (User Based)

intEstablishedHandlerCB (OpsecSession *pSession){ CPMISessionBindUser (pSession, g_szUserName, g_szUserPasswd BindHandlerCB, , &opid); return OPSEC_SESSION_OK;}eOpsecHandlerRCBindHandlerCB (OpsecSession *pSession, cpresult stat, void * pvOpaque){ /*Open database and continue.*/ return OPSEC_SESSION_OK;}intEndHandlerCB (OpsecSession *pSession){ return OPSEC_SESSION_END;}

NULL

int main (int ac, char ** av){ OpsecEntity *pClientEntity; OpsecEntity *pServerEntity; OpsecEnv *pEnv; OpsecSession *pSession; pEnv = opsec_init (OPSEC_SIC_NAME, “CN=my_opsec_app, 0=London.mydomain.com.n56gts”, OPSEC_EOL);

pServerEntity = opsec_init_entity(pEnv, CPMI_SERVER, OPSEC_SERVER_IP, uip /* = server_ip */, OPSEC_SERVER_AUTH_PORT, (int)htons(18190), OPSEC_ENTITY_SIC_NAME, “CN=cp_mgmt,0=paris.mydomain.com.n79vjo”, OPSEC_EOL);

pClientEntity = opsec_inity_entity(pEnv, CPMI_CLIENT, OPSEC_SESSION_ESTABLISHED_HANDLER, EstablishedHandlerCB, OPSEC_SESSION_END_HANDLER, EndHandlerCB, OPSEC_EOL); CPMISessionNew (pClientEntity, pServerEntity, 0, &pSession); opsec_mainloop(pEnv); opsec_destroy_entity(pServerEntity); opsec_destroy_entity(pClientEntity); opsec_env_destroy(pEnv);}

OPSEC_SERVER_AUTH_TYPE, OPSEC_ASYM_SSLCA,


pServerEntity = opsec_init_entity(pEnv, CPMI_SERVER, OPSEC_SERVER_IP, uip /* = server_ip */, OPSEC_SERVER_AUTH_PORT, (int)htons(18190), OPSEC_ENTITY_SIC_NAME, “CN=cp_mgmt,0=paris.mydomain.com.n79vjo”, OPSEC_EOL);


OPSEC_SERVER_AUTH_TYPE, OPSEC_ASYM_SSLCA,


38

The following asymmetric authentication methods can be used when creating the Server Entity (OPSEC_SERVER_AUTH_TYPE):

• OPSEC_ASYM_SSLCA

• OPSEC_ASYM_SSLCA_COMP

• OPSEC_ASYM_SSLCA_RC4

• OPSEC_ASYM_SSLCA_RC4_COMP

OPSEC_SIC_NAME for opsec_init API must specify the full DN (Distinguished Name).

The second is to use an an Application Certificate

1. Define an OPSEC application via the Smart Dashboard and make sure the CPMI client check box is checked.

2. Press the communication button to create a certificate for the application.

3. Use <opsec_pull_cert> to get the certificate (see the “Pulling Certificates” section of the “OPSEC API Specification”).

Session Version Identification

Timeouts, major and minor versions,High Availability mode,server type and server install type can all be retreived. For more information the specific API’s are located in CPMI Sessions and Connections page 67.

CPMIGetMajorReleaseVer and CPMIGetMinorReleaseVer to determine if the application will run properly with current CPMI client and server versions.Figure 1-5 A. Callback DefinitionsintEstablishedHandlerCB (OpsecSession * pSession){ CPMISessionBnd (pSession, BindHandlerCB, N

return OPSEC_SESSION_OK;

eOpsecHandlerRCBindHandlerCB (OpsecSession *pSession, cpresult_{ /* Open a database and continue. */ return OPSEC_SESSION_OK;}

Partial Object Retrieval


Note - the call for CPMISessionBind in the callback definition of EstablishHandlerCBFigure 1-6 B. Establishing the Session (Certificate Based)

The following symmetric authentication methods can be used when creating the Server Entity (OPSEC_SERVER_AUTH_TYPE):

• OPSEC_SSLCA

• OPSEC_ASYM_SSLCA_COMP

• OPSEC_ASYM_SSLCA_RC4

• OPSEC_ASYM_SSLCA_RC4_COMP

• OPSEC_SSLCA_CLEAR

OPSEC_SIC_NAME for opsec_init API must specify the full DN (Distinguished Name).

Partial Object RetrievalA Client can retrieve a partial Object. Objects in the Check Point Database typically have a large number of fields. These fields are used in various tasks that the Objects perform. In many cases a Client that uses an Object only uses a relevant sub-set of the Object’s fields.


pServerEntity = opsec_init_entity(pEnv, CPMI_SERVER, OPSEC_SERVER_IP, uip /* = server_ip */, OPSEC_SERVER_AUTH_PORT, (int)htons(18190), OPSEC_ENTITY_SIC_NAME, “CN=cp_mgmt,0=paris.mydomain.com.n79vjo”, OPSEC_SERVER_AUTH_TYPE, OPSEC_SSLCA, OPSEC_EOL);



pServerEntity = opsec_init_entity(pEnv, CPMI_SERVER, OPSEC_SERVER_IP, uip /* = server_ip */, OPSEC_SERVER_AUTH_PORT, (int)htons(18190), OPSEC_ENTITY_SIC_NAME, “CN=cp_mgmt,0=paris.mydomain.com.n79vjo”, OPSEC_SERVER_AUTH_TYPE, OPSEC_SSLCA, OPSEC_EOL);


Partial Object Retrieval

40

CPMI Context ObjectsClients retrieve relevant Objects by adding a CPMI Context object to retrieval functions. A Context Object holds a list of field names. Retrieving objects by Context means that the resulting objects will only contain the fields that were registered in the Context Object.

The asterisk “*” character can be used as a special kind of field name in side a Context. When a Context contains the asterisk field name, it will return all fields of an object. Adding other field names to a Context containing the asterisk field will not damage anything but it has no meaning.

Table 1-21 Functions for Context Creation and Manipulation

function name description see...

CPMIContextCreate Create a context of a specific type. page 134

CPMIContextAddField Add a field name to the context. page 134

CPMIContextRemoveField Remove a field name from the context. page 135

Note - There is only one type of Context called dynamic_context that can be passed.

Table 1-22 Functions that Accept a Context Handle(s)

function name description see...

CPMIDbQueryTablesByContext Query objects from multiple tables with a query and a Context for each.

page 94

CPMITblGetObjByContext Get an object only with in the in-Context fields.

page 107

CPMITblQueryObjectsByContext Query objects. Results contain only the in-Context fields.

page 111

CPMIRefSetContext Set a Context into a reference. page 159

Object Referencing


Object ReferencingAn object may be referred to using a reference (HCPMIREF) handle. This handle identifies the object both by its name, and by the name of the table which contains the object. This handle may then be used as a Linked Object attribute, the parent object references its child by its HCPMIREF (based on object’s name and table’s name).

For example, suppose we have an object of class certificate. This object has a field named ca of type linked_object see Table 1-23.

To retrieve the actual ca object, the field must be de-referenced as follows:

Table 1-23 Object Referencing Example

Class Certificate (owned)

name type valid values default value M/O

#certreq-pki-gen boolean

#pki-host-cert-set boolean

ca linked_object

ca server

dn string

pkisignkey string

status string unsigned, signed unsigned

stored at string management_server, module

management_server

HCPMIOBJ hCert = GetMyCertificate (...); /*NOT a cpmi function*/tCPMI_FIELD_VALUE fv;

CPMIObjGetFieldValueByName (hCert, "ca", &fv); /* the actual HCPMIOBJ is returned in MyDerefCB*/

CPMIRefGetReferencedObj ( fv.refFv, /*HCPMIREF handle*/ hMyDb, /*HCPMIDB handle*/ MyDerefCB, /*my callback*/ MyOpaque, /*my opaque to MyDerefCB*/ &opid); /*returned cpmiopid*/

Object Uniqueness

42

Notice that the format of “MyDerefCB” which is of type “CPMIObj_CB” is as follows:

The HCPMIOBJ handle of the object (“ca”) will be returned here.

The functions that handle object referencing and de-referencing are listed below:

Object UniquenessEach object in the Check Point object repository is assigned a unique ID (UID) when it is created. This ID is guaranteed to be unique within the database and across databases. One important feature of the object uniqueness is the ability to use it for object comparison.

In addition, an object’s name must be unique within the table which contains the object.

typedef eOpsecHandlerRC (*pfnCPMIObj_CB)(HCPMIDB hDb, HCPMIOBJ hObj, cpresult stat, cpmiopid opid, void *pvOpaque);

Note - To complete, the following “typedef” is applicable: “typedef pfnCPMIObj_CB CPMIObj_Cb;”

Table 1-24 object referencing functions


CPMIRefCreateFromName creates a reference to an object based on the object’s name and the table’s name

page 156

CPMIRefCreateFromObj creates a reference to an object based on the object’s handle

page 157

CPMIRefGetReferencedObj retrieves the object pointed to by the specified reference

page 157

CPMIRefGetObjectName retrieves the name of the object pointed to by the specified reference

page 158

CPMIRefGetTableName retrieves the name of the table containing the object pointed to by the specified reference

page 159

Notification


The following functions manage object UIDs

NotificationThe CPMI notification mechanism enables CPMI Clients to track modifications made to the Check Point object repository by other CPMI applications.

The CPMI Client registers events for which it wants to receive notifications. These sets of events may be associated with a specific object, table or the entire database, in order to aquire the appropriate handle if any additional behavior is required.

The set of events can also be applied to an application (represented by an application object) and can monitor status changes. These events include:

• Object creation, modification, deletion and renaming

• Installation or uninstalling of a policy

• Status object notification

Events are registered by calling CPMIDbRegisterEvent (see page 195) with the appropriate parameters. To un-register an events (i.e. to stop receiving notification for it), call CPMIDbUnRegisterEvent (see page 197).

Table 1-25 object UID functions


CPMIObjGetUid retrieves the object’s UID page 126

CPMIUidAreEqual determines whether two UIDs are identical

page 163

CPMIUidToString converts a UID to string format page 164

CPMIUidFromString converts a string to UID format page 164

Locking Objects

44

Once the event occurs, the CPMI Client receives a notification message. The following functions retrieve information based on this notification message:

Registration to events will become invalid (thus, no notification will be sent) once those object are deleted, or change the version of the object, for example from Version 4.1 to NG.

Locking ObjectsObjects in the Check Point object repository may be locked in order to ensure exclusive Write access to that object. When an object is locked, all its attributes, owned, linked, and member objects are locked as well. This verifies no one can apply changes while an object is being locked and ensures the appropriate logic of your application.

Once the required application logic, requiring the lock has been completed it is important to release the lock of the object immediately. Failing to do so may cause problems to your own and other applications at run time.

Table 1-26 notification management functions


CPMINotifyGetEvent retrieves the event that triggered the event

page 198

CPMINotifyGetModiferHost retrieves the name of the machine from which the event was triggered

page 199

CPMINotifyGetModiferUser retrieves the name of the administrator whose modification triggered the event

page 200

CPMINotifyGetObj retrieves the handle of the object that triggered the event (valid only for Status Objects)

page 200

CPMINotifyGetObjName retrieves the name of the object that triggered the event

page 201

CPMINotifyGetTblName retrieves the name of the table containing the object that triggered the event

page 201

CPMINotifyGetTime retrieves the time of the event page 202

CPMINotifyGetUid retrieves the UID of the object that triggered the event

page 199

Caching


The following functions lock and unlock objects:

CachingIn order to improve network performance and loading large data chunks (such as schema definitions and heavy query results) CPMI supports a Client side encrypted cache mechanism which is disabled by default. To enable the caching, a specific call to CPMISessionUseCache needs to be issued with CP_S_OK as a parameter. Calling the same function with CP_S_FALSE as a parameter disables the cache.

The default directory for the enabled cache is ./CPMICache. To change the path, after the connect command but before the bind, call CPMISessionSetCachePath with the desired path as a parameter. (for more information on CPMISessionSetCachePath see page 72).

QueriesCPMI queries enable the Client to request objects that meet certain criteria. These criteria syntax takes a generic formed of the following conditions:

The attribute value can be one of the following:

• string:A string value must be quoted (e.g. ‘floodgate_application’)and may contain asterisk (*) wildcards which represent any character combination including none. Asterisk characters appearing within a string value in a < or > condition are treated as regular characters.

• example: color=’b*’ returns all black and blue colors from the desired table

Table 1-27 object lock and release functions


CPMIObjAcquireLock locks the object page 118

CPMIObjReleaseLock releases the object lock page 120

attr_name = Valueattr_name < Valueattr_name > Value

Note - Use single-quotation marks (‘’) around the attribute value.

Queries

46

• integer:An integer must be non-quoted, all digits and have no decimal points (e.g. 100). Numeric values enforce their type on the tested attribute without error detection (ie. the value held by the attribute will be converted to the respective numeric type). A quoted numeric value is considered a string.

• real:A real must be non-quoted, all digits and contain 1 decimal point (e.g. 1.5). Numeric values enforce their type on the tested attribute without error detection (ie. the value held by the attribute will be converted to the respective numeric type). A quoted numeric value is considered a string.

Queries can be made more complex by writing a more complicated criteria using ‘&’- AND, ‘|’ – OR and ‘!’ – NOT and by controlled evaluation order through the use of parentheses ().

Queries are implemented using CPMITblQueryObjects (see page 111) or CPMITblQueryByContext (see “CPMITblQueryObjectsByContext” on page 111).

For example, the following code fragment illustrates how to fetch all Floodgate Application Objects

hMyTbl represents the handle of the Application objects table. The type is used to categorize a specific family within the table itself. Omitting the ‘type’ equality will bring as a result the whole set of objects from the specified table answering the relevant criteria.

The result set of the Query will be available once the callback MyQueryCB returns holding the result in the HCPMIRSLT result variable.

Notice that the format of this callback takes the following format:

CPMITblQueryObjects (hMyTbl, "type='floodgate_application'", MyQueryCB, MyOpaque, &opid);

typedef eOpsecHandlerRC (*pfnCPMIQuery_CB) (HCPMIDB hDb, HCPMIRSLT result, cpresult stat, cpmiopid opid, void * pvOpaque);

Object Status Monitoring


An example of a more complex query:

Object Status MonitoringA status object is created automatically for each application object in the Check Point object repository, when information about the application object status is required.

Information about an object’s status can be managed in one of two ways:

• By calling CPMIDbRegisterEvent with the eCPMI_NOTIFY_STATUS_CHANGE flag (see page 195). This registers the object for status change notification. The eCPMI_NOTIFY_STATUS_CHANGE flag serves as periodic notification of object status changes. The successive flow of notifications is stopped after a call to the opposite API “CPMIDbUnregisterEvent” on page 197.

• By calling “CPMIDbGetAppsStatus” on page 146 to get immediate status regarding the object.

AuditingObject modifications auditing and administration can be done using the following functions:

CPMITblQueryObjects (hMyTbl,................."type=’cp_license’” &expiration_date=’some_value’”,MyQueryCB,MyOpaque,&opid);

Table 1-28 auditing and administration functions


CPMIObjGetLastModifier retrieves the name of the last administrator who modified the object

page 128

CPMIObjGetLastModifierHost retrieves the machine name from which the object was last modified

page 128

CPMIObjGetLastModificationTime retrieves the time object was last modified

page 129

Iteration

48

This set of APIs provides the ability to fetch the latest changes information for specific objects. Changes introduced by any other CPMI based application (internal or external) will be tracked and written into the log audit file which is a binary file. The full scope of modifications can be viewed by using the SmartView Tracker’s Audit functionality, or by implementing a LEA (Log Export API) application that fetches auditing information from the SmartCenter Server.

IterationIteration is a basic functionality for developing a CPMI based application. CPMI provides functions for iterating through databases, tables, containers, objects, query results, and more.

For each type of iteration, CPMI provides the following functionality:

Where YYY can be ‘Fld’ for fields iteration, ‘Obj’ for object iteration, ‘Tbl’ for table iteration, ‘Db’ for database iteration, ‘Cntr’ for Containers iteration and ‘OrderCntr’ for Ordered Containers.

Table 1-29 iteration functions

function name description

CPMIUUUIterVVV where the following set of APIs are being supported:CPMISessionIterDb, (see page 95)CPMIDBIterTables, (see page 102)CPMIDBIterClasses, (see page 151)CPMIResultIterObj, (see page 112)CPMICntrIterElements, (see page 168)CPMIOrderCntrIterElements, (see page 176)CPMIClassIterFields, (see page 189)

CPMIIterYYYGetNext retrieves the next element in the iteration object

CPMIIterYYYGetCount

retrieves the number of elements in the iteration object

CPMIIterYYYIsEmpty determines whether iterator object is empty

CPMIIterYYYIsDone determines whether iteration is complete

CPMIIterYYYRestart starts the iteration over from the beginning

Event Handling


Event HandlingThe CPMI Client responds to the events listed in Table 1-30 below.

The API functions that trigger these events are asynchronous, and each takes an event handler or callback function as one of its arguments.

The fact that these functions are asynchronous means that they return before they complete processing. For example, CPMIDbOpen creates a pointer to the database immediately, but the actual result of its attempt to open the database may not be known for some time. When this result becomes available, the client side is being notified by calling the CPMIDb_CB callback function with the appropriate opid argument.

Asynchronous functions provide return values at two different times:

1. when they return, as all functions do

At this time, they provide a value for cpmiopid, a unique operation code that can be used to match the event to the function that triggered that event.

2. when they have completed their task, as the arguments passed to the callback function.

Table 1-30 CPMI Events

event callback function see also

The connection to the SmartCenter Server has been authenticated.

CPMIBind_CB page 204

A certificate has been created or pushed. CPMICertificate_CB page 205

An object has been created, retrieved from database, de-referenced, or deleted.

CPMIObj_CB page 206

A registered event has occurred. CPMINotify_CB page 207

The database has been opened, a policy has been installed or un-installed, an object has been updated, or locked, or deleted from a table.

CPMIDb_CB page 208

Results to query or status for applications are available.

CPMIQuery_CB page 209

A license has been attached or detached. CPMILicense_CB page 209

Event Handling

50

Each return value provides information of a different kind. For example, if CPMIDbOpen were unable to allocate memory for the database handle, it would return an error code to indicate failure (see “Error Codes” on page 212).

If CPMIDbOpen were unable to resolve its database argument, CPMIDbOpen would return a non-NULL pointer to the database but CPMIDb_CB would be called with its stat argument set to the appropriate error value.

In other words, a function that calls CPMIDbOpen does not know whether the database was opened or not, and so should not assume that the database is accessible even though the pointer to the database itself may be valid. However, the specified callback function CPMIDb_CB does know whether the database was opened, and can access the database accordingly. This is illustrated in Figure 1-7.Figure 1-7 Event Handlers and Return Values

{ cpresult res; … res = CPMIServerBind(... , after_bind, ...); if (CPMI_FAILED(res))) { … }}

eOpsecHandlerRc after_bind(..., cpresult stat, ...){ if (stat != CP_S_OK) { ... } … res2=CPMIDbOpen(..., after_open, ...); if (CPMI_FAILED(res2)) { … } …}

eOpsecHandlerRC after_open(..., cpresult stat, ...){ …}

CPMIServerBindreturns here …

but its “real” resultis only known here …

CPMIDbOpenreturns here …


used

callback function

used

callback function

{ cpresult res; … res = CPMIServerBind(... , after_bind, ...); if (CPMI_FAILED(res))) { … }}

eOpsecHandlerRc after_bind(..., cpresult stat, ...){ if (stat != CP_S_OK) { ... } … res2=CPMIDbOpen(..., after_open, ...); if (CPMI_FAILED(res2)) { … } …}

eOpsecHandlerRC after_open(..., cpresult stat, ...)

CPMIServerBindreturns here …


CPMIDbOpenreturns here …


used

callback function

used

callback function

Fields data type mapping


Fields data type mappingAs described in “Fields” on page 17, fields type mapping is a necessity. This mapping, maps the actual schema defined types and the “C” data types, as described by enum of tCPMI_FIELD_TYPE. For schema data types, refer to “Details” on page 55.Figure 1-8 C Coding Types

enum tagCPMI_FIELD_VALUE_TYPE{eCPMI_FVT_UNDEFINED = 0 /*Used only by CPMI to indicate error*/,eCPMI_FVT_CTSTR /*null terminated const string value*/,eCPMI_FVT_BOOL /*boolean value*/,eCPMI_FVT_NUM /*numeric value*/,eCPMI_FVT_U_NUM /*unsigned numeric value*/,eCPMI_FVT_NUM64 /*64bit numeric value*/,eCPMI_FVT_U_NUM64 /*unsigned 64bit numeric value*/,eCPMI_FVT_OBJ /*HCPMIOBJ value*/,eCPMI_FVT_REF /*HCPMIREF value*/,eCPMI_FVT_CNTR /*HCPMICNTR value*/,eCPMI_FVT_ORDERED_CNTR /*HCPMIORDERCNTR value*/,};/* typedef for tagCPMI_FIELD_TYPE */typedef enum tagCPMI_FIELD_TYPE tCPMI_FIELD_TYPE;

Fields data type mapping

52

Table 1-31 Schema defined types and coding data types mapping

Schema defined types Coding data type Description

string eCPMI_FVT_CTSTR String field

int eCPMI_FVT_NUM Numeric field

u_int eCPMI_FVT_U_NUM Unsigned numeric field

int_64 eCPMI_FVT_NUM64 64 bit numeric field

u_int_64 eCPMI_FVT_U_NUM64 Unsigned 64 bit numeric field

boolean eCPMI_FVT_BOOL Boolean field

owned_object eCPMI_FVT_OBJ Owned object field

linked_object eCPMI_FVT_REF Linked object field

member_object eCPMI_FVT_REF Member object field

Multiple value – ‘M’ eCPMI_FVT_CNTR Container field

Multiple value – ‘O’ eCPMI_FVT_ORDERED_CNTR Ordered container field

53

Chapter 2Schema

In This Chapter

Overview page 54

Details page 55

Overview

54

OverviewCPMI API is based upon clear object definition. Those definitions are described in a set of schema files, termed as Check Point Object Definition Files, though, this terminology is used interchangeably and refers distinctly as to what and how an object is defined. Schema definitions are loaded into memory once the CPMI Server on the SmartCenter Server have started and serve the basic functionality of the CPMI Server. Objects are validated according schema definitions, and must comply with the full set of attributes of the class the object is associated with. An object is an instantiation of a class definition.

The definition files are formatted with Check Point’s format. The easiest way to view and understand the object definitions hierarchy is via the HTML format help file CPMI_schema.html, located in the OPSEC documentation package. This single HTML file containing the database hierarchy and is made up of three major sections:

• List of tables and names of classes associated with a specific table

• List of owned object classes

• List of actual object class definitions

For more details regarding the list of tables supported by CPMI, see “Tables” on page 23.

Details

Chapter 2 Schema 55

DetailsSee Table 2-1 for ‘network_objects’ table, servers and services tables.

Table 2-1 Schema Table Network Objects

Clicking on class entry under the desired table will display the actual class definition of that class, as follows in Table 2-2:

Table 2-2 Schema Class Network (table network_objects)

Details

56

Table 2-3 gives the full details for the ‘network’ object definition as follows:

Clicking on the valid values of ‘NAT’ attribute, which is of ‘owned object’ type (see “Fields” on page 17) will display the actual definition of the ‘NAT’ owned object, as follows:

Table 2-3 Details of Table 2-2 Schema Class Network

object definition example

title object name table name associated with this object

Class network (table network_objects)

name name of attributes of the object

edges

type data type of the attribute which can take any of the supported basic data types of CPMI such as: string, boolean etc. see “Fields data type mapping” on page 51 for the actual field data types and mapping between schema entries and the ‘enum’ definitions.

linked_object

valid values values which are permitted for the specific attributes can take the format of a single value, multiple values (comma separated) or a range of values.

ambiguous_network, provisory_network, network

default value initial value associated with this field upon creation or reset.

none

M/O If field may contain multiple values then “M” stands for multiple and “O” stands for ordered

M

Details

Chapter 2 Schema 57

Table 2-4 Class NAT (owned)

If we further want to discover the hierarchy of the object and find out the valid values for the ‘the_firewalling_obj’, which is of type “linked_object” (see “Fields” on page 17), then on clicking the ‘embedded_device’, which is one of the possible valid values for this field, the following screen will show up (partial display):

Table 2-5 Class embedded_device (table network_objects)

Note - The indication is uni-directional, that is from the parent object to its child member, and not the other way round.

Special Schemes

58

Special Schemes

host_schemes_valThe host_schemes_val located in the gateway_ckp object under the owned object firewall_setting enables authorization methods like firewall password, s/key etc. This field accepts a 0-127 numeric value.

Using “or”, any combination of the above values are valid.

Example:

114 is the default: S/Key SecurID, Radius, Defender and TACACS (0+2+16+32+64=114).

Table 2-6 Values Table for host_schemes_val

numeric values authorization method

S/Key 0

SecurID 2

OS Password 4

Internal Password 8

Radius 16

Defender 32

TACACS 64

59

Chapter 3API Functions

In This Chapter

Function Calls page 60

Event Handlers page 204

Error Codes page 212

Function Calls

60

Function CallsThis section describes the functions provided by the OPSEC CPMI API. Unless noted otherwise, the function prototypes are defined in the file CPMIClientAPIs.h.

In This Section

Memory Allocation page 61

CPMI General Utilities page 64

CPMI Sessions and Connections page 67

CPMI Requests page 73

Databases page 80

Tables page 99

Objects page 106

Contexts page 134

Applications page 139

Classes in a Schema page 147

Reference, Iteration and ID of Objects page 156

Elements page 165

Fields page 179

Errors page 192

Event Registration and Notification page 195

Memory Allocation

Chapter 3 API Functions 61

Memory AllocationThe functions described below manage string and handle allocation.

In This Section

CPMIFreeString

CPMIFreeString frees strings allocated by various CPMI API functions.

Prototypevoid CPMIFreeString(char* sz);

Arguments

Return Values

None.

Notes

CPMIHandleAddRef

CPMIHAddRef increments the handle reference count. Use it to explicitly increment the reference count of the handle in order to make sure the handle remains valid.

example:

CPMIFreeString page 61

CPMIHandleAddRef page 61

CPMIHandleRelease page 62

CPMIReleaseFieldValue page 63

Table 3-1 CPMIFreeString arguments

argument meaning

sz A pointer to the string to be freed.

Note - The lifetime of the handle is controlled by the hidden property “reference count”. When the reference count reaches 0 the handle destroys itself. Every CPMI API that returns handle as an out parameter increases the reference count of the handle before returning it. After calling an API the caller should decrease the reference count to avoid memory leaks.

Memory Allocation

62

use CPMIHAddRef every time you make a copy of a CPMI handle since other functions that also have copies may call CPMIHandleRelease (see below) making your copy invalid.

Prototypeunsigned long CPMIHandleAddRef(HCPMI handle);

Arguments

Return Values

The new reference count if successful.

CPMIHandleRelease

CPMIHandleRelease decrements the handle reference count. Use this function to release holding of CPMI handle that was returned by some CPMI API, or a handle passed to CPMIHandleAddRef.

For safety, after call to CPMIHandleRelease, assign the handle to NULL.

Prototypeunsigned long CPMIHandleRelease (HCPMI handle);

Arguments

Return Values

The new reference count if successful.

Table 3-2 CPMIHandleAddRef arguments

argument meaning

handle The handle to increment.

Table 3-3 CPMIHandleRelease arguments

argument meaning

handle The handle to decrement.

Memory Allocation


CPMIReleaseFieldValue

CPMIReleaseFieldValue releases the string or field handle (according to the fvt member) in the designated tCPMI_FIELD_VALUE. For tCPMI_FIELD_VALUE’s see Table 3-185. Call CPMIReleaseFieldValue instead of checking tCPMI_FIELD_VALUE’s fvt member and then call CPMIHandleRelease on the appropriate member handle.

Prototypevoid CPMIReleaseFieldValue (tCPMI_FIELD_VALUE *pFv);

Arguments

Return Values

None.

Notes

CPMIFreeString is called on pFv->strVal.

CPMIReleaseHandle is called on the various handle fields.

pFv->fvt is set to eCPMI_FVT_UNDEFINED.

Table 3-4 CPMIReleaseFieldValue arguments

argument meaning

pFv The structure whose field is to be released.

CPMI General Utilities

64

CPMI General UtilitiesThis section describes the CPMI utility functions.

CPMIGetMajorReleaseVer

CPMIGetMajorReleaseVer retreives the CPMI client library major version. CPMIGetMajorReleaseVer should be used together with CPMIGetServerMajorReleaseVer, CPMIGetServerMinorReleaseVer and CPMIGetMinorReleaseVer to determine if the application will run properly with current CPMI client and server versions.

Prototypecpresult CPMIGetMajorReleaseVer (unsigned int * pMajorVer);

Argument

Return Value

CP_S_OK, CP_E_INVALIDARG

CPMIGetMinorReleaseVer

CPMIGetMinorReleaseVer retrieves the CPMI client library minor version. CPMIGetMinorReleaseVer should be used together with CPMIGetServerMajorReleaseVer, CPMIGetServerMinorReleaseVer and CPMIGetMinorReleaseVer to determine if the application will run properly with current CPMI client and server versions.

Prototypecpresult CPMIGetMinorReleaseVer (unsigned int * pMinorVer);

CPMIGetMajorReleaseVer page 64

CPMIGetMinorReleaseVer page 64

Table 3-5 CPMIGetMajorReleaseVer arguments

argument meaning

pMajorVer The address of an unsigned int variable that receives the major release version.



Argument

Return Value


CPMIGetServicePackVer

CPMIGetServicePackVer retreives the CPMI client library service pack version number. The version retrieval functions CPMISessionGetServerMajorVersion, CPMISessionGetServerMinorVersion, CPMISessionGetServerSPVersion, CPMISessionGetServerHFVersion, CPMISessionGetServerBuildNumber, CPMIGetMajorReleaseVer, CPMIGetMinorReleaseVer, CPMIGetServicePackVer, CPMIGetHotFixVer and CPMIGetBuildVer can be used to determine if the application will run properly with current CPMI client and server versions.

Prototype

cpresult CPMIGetServicePackVer (unsigned int * pSPVer);

Argument

Return Value


CPMIGetHotFixVer

CPMIGetHotFixVer retreives the CPMI client library hotfix version number. The version retrieval functions CPMISessionGetServerMajorVersion, CPMISessionGetServerMinorVersion, CPMISessionGetServerSPVersion, CPMISessionGetServerHFVersion, CPMISessionGetServerBuildNumber,

Table 3-6 CPMIGetMinorReleaseVer arguments

argument meaning

pMinorVer The address of an unsigned int variable that receives the minor release version.

Table 3-7 CPMIGetServicePackVer arguments

arguments meaning

pSPVer The address of an unsigned int variable that receives the service pack release version.


66

CPMIGetMajorReleaseVer, CPMIGetMinorReleaseVer, CPMIGetServicePackVer, CPMIGetHotFixVer and CPMIGetBuildVer can be used to determine if the application will run properly with current CPMI client and server versions.

Prototype

cpresult CPMIGetHotFixVer (unsigned int * pHFVer);

Argument

Return Value


CPMIGetBuildVer

CPMIGetBuildVer retreives the CPMI client library build number. The version retrieval functions CPMISessionGetServerMajorVersion, CPMISessionGetServerMinorVersion, CPMISessionGetServerSPVersion, CPMISessionGetServerHFVersion, CPMISessionGetServerBuildNumber, CPMIGetMajorReleaseVer, CPMIGetMinorReleaseVer, CPMIGetServicePackVer, CPMIGetHotFixVer and CPMIGetBuildVer can be used to determine if the application will run properly with current CPMI client and server versions.

Prototype

cpresult CPMIGetBuildVer (unsigned int * pBuildNum);

Argument

Return Value


Table 3-8 CPMIGetHotFixVer arguments

arguments meaning

pHFVer The address of an unsigned int variable that receives the hotfix version.

Table 3-9 CPMIGetHotFixVer arguments

arguments meaning

pBuildNum The address of an unsigned int variable that receives the build number.

CPMI Sessions and Connections


CPMI Sessions and ConnectionsThis section describes the functions that manage the CPMI session and bind the connection.

In This Section

CPMISessionNew

Create an OpsecSession to be used by CPMI APIs

Prototypecpresult CPMISessionNew (OpsecEntity * pClientEntity,

OpsecEntity * pServerEntity, int nTimeout, OpsecSession ** ppSession);

Arguments:

Return Value

CP_S_OK, CP_E_FAIL, CP_E_INVALIDARG, and CPMI_E_OPSEC_SESSION.

CPMISessionNew page 67

CPMISessionEnd page 68

CPMISessionBindUser page 68

CPMISessionBind page 69

CPMIDbCreateCertificate page 70

CPMIDbRevokeCertificate page 71

CPMISessionSetCachePath page 72

CPMISessionUseCache page 73

Table 3-10 CPMISessionNew arguments

argument meaning

pClientEntity Entity representing the client

pServerEntity Entity representing the server

nTimeout Timeout to wait for any request [milliseconds]

ppSession Returned OpsecSession


68

CPMISessionEnd

CPMISessionEnd ends a given session.

Prototypecpresult CPMISessionEnd (OpsecSession * pSession);

Arguments

Return Values


CPMISessionBindUser

CPMISessionBindUser binds the connection using user information.

Prototypecpresult CPMISessionBindUser (OpsecSession * pSession,

const char * szUserName, const char * szUserPasswd, CPMIBind_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Table 3-11 CPMISessionEnd arguments

argument meaning

pSession Valid OpsecSession



Arguments

Return Value

CP_S_OK, CP_E_INVALIDARG, and case specific error codes.

CPMISessionBind

CPMISessionBind binds the connection based on information given at the entity creation time.

Prototypecpresult CPMISessionBind (OpsecSession * pSession,

CPMIBind_CB pfnCB, void * pvOpaque, cpmiopid * pOpid);

Table 3-12 CPMISessionBindUser arguments

argument meaning

pSession Valid OPSEC session

szUserName User name on database

szUserPasswd User password on database

pfnCB User function to be called when operation is done (see CPMI Client side data types for list of callback prototypes)

pvOpaque User data to pass to pfnCB

pOpId Address of cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure. (for an explanation of operation id see Table 3-216)


70

Arguments

Return Value

CP_S_OK, CP_E_INVALIDARG, and CPMI_E_SESSION_NOT_CONNECTED.

CPMIDbCreateCertificate

CPMIDbCreateCertificate enables creation of a new certificate. The purpose of this API is to create a certificate for an Administrator and to change it’s connection state from ‘uninitialized’ to ‘communicating’.

Prototypecpresult CPMIDbCreateCertificate (HCPMIDB hDb,

HCPMIOBJ hObj,const char* szPasswd, CPMIDBCertificate_CB pfnDbCertificateCB, void * pvOpaque, cpmiopid * pOpid);

Table 3-13 CPMISessionBind arguments

argument meaning

pSession Valid OPSEC session

pfnCB User function to be called when operation is done (see CPMI Client side data types for list of callback prototypes.)

pvOpaque User data to pass to pfnCB.

pOpId Address of cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure. (for an explanation of operation id see Table 3-216).

Note - CPMI can use caching to improve program performance. By default caching isn’t used, explicitly call CPMISessionUseCache (see below) to enable caching.



Arguments

Return Value

CP_S_OK, CP_E_INVALIDARG, CP_S_OK, CP_E_FAIL, CPMI_E_DB_READ_ONLY.

CPMIDbRevokeCertificate

CPMIDbRevokeCertificate revokes a certificate created with CPMIDbCreateCertificate. The purpose of this API is to revoke a certificate created for an Administrator and to change it’s connection state from ‘communicating’ to ‘uninitialized’.

Prototypecpresult CPMIDbRevokeCertificate (HCPMIDB hDb,

HCPMIOBJ hObj, const char* szPasswd, CPMIDBCertificate_CB pfnDbCertificateCB, void * pvOpaque, cpmiopid * pOpid);

Table 3-14 CPMIDbCreateCertificate arguments

argument meaning

hDb Handle to the database object.

hObj Handle to the object.

szPasswd The password for internal certificate authority (ICA).

pfnDbCertificateCB In this callback function the user gets an indication of a successful request with the new certificate and sic_name.




72

Arguments

Return Value


CPMISessionSetCachePath

CPMISessionSetCachePath sets a cache directory for the Client library and indicates to the Client to use local caching. By default for local caching, if this function is not called CPMI uses the ./CPMICache/directory.

Prototypecpresult CPMISessionSetCachePath (OpsecSession * pSession,

const char * szpath);

Arguments

Return Values

CP_S_OK, CP_E_FAIL, CP_E_INVALIDARG

Table 3-15 CPMIDbRevokeCertificate arguments

argument meaning


hObj Handle to the object.

szPasswd The password for internal certificate authority (ICA).

pfnDbCertificateCB In this callback function the user gets an indication of a successful request.



Table 3-16 CPMISessionSetCachePath arguments

argument meaning

pSession A valid binded session.

szpath A path (directory name) for storing cache files.

CPMI Requests


CPMISessionUseCache

CPMISessionUseCache indicates whether or not to use local caching to improve network performance. By default there is no use of the local cache so the client need to call this API in order to use the caching ability.

Prototypecpresult CPMISessionUseCache (OpsecSession * pSession, cpresult bUse);

Arguments

Return Values

CP_S_OK, CP_E_FAIL, CP_E_INVALIDARG.

CPMI RequestsCPMI asynchronous functions are handled in two phases. In the first phase, a request for information is sent. When that information becomes available, the corresponding callback function is called.

The following functions enable you to cancel CPMI requests and manage CPMI request timeouts.

In This Section

Table 3-17 CPMISessionUseCache arguments

argument meaning

pSession A valid binded session.

bUse flag with CP_S_OK or CP_S_FALSE.

CPMISessionSetTimeout page 74

CPMISessionGetTimeout page 74

CPMISessionGetServerMajorVersion page 75

CPMISessionGetServerMinorVersion page 75

CPMISessionGetServerHAMode page 76

CPMISessionGetServerType page 76

CPMISessionGetServerRunType page 77

CPMISessionGetServerInstallType page 77

CPMI Requests

74

CPMISessionSetTimeout

CPMISessionSetTimeout sets a new timeout for future session operations.

Prototypecpresult CPMISessionSetTimeout (OpsecSession * pSession, int nTimeout);

Argumentsts

Return Values

CP_S_OK, CP_E_FAIL and CP_E_INVALIDARG

CPMISessionGetTimeout

CPMISessionGetTimeout gets the timeout in milliseconds. Used in given session operations.

Prototypecpresult CPMISessionGetTimeout (OpsecSession * pSession, int * pTimeout);

Argument

Return Value


Table 3-18 CPMISessionTimeout arguments

argument meaning

pSession Valid OpsecSession

nTimeout new timeout (in milliseconds)

Table 3-19 CPMISessionGetTimeout arguments

argument meaning

pSession A valid OPSEC Session

pTimeout Returned timeout (in milliseconds). On failure, *pTimeout is set to -1.

CPMI Requests


CPMISessionGetServerMajorVersion

CPMISessionGetServerMajorVersion retreives the major version name. CPMISessionGetServerMajorVersion should be used together with CPMISessionGetServerMinorVersion, CPMIGetMajorReleaseVer and CPMIGetMinorReleaseVer to determine if the application will run properly with current CPMI client and server versions.

Prototypecpresult CPMISessionGetServerMajorVersion (OpsecSession * pSession,

unsigned int * pMajorVer);

Argument

Return Value


CPMISessionGetServerMinorVersion

CPMISessionGetServerMinorVersion retrieves the CPMI server minor version. This function, together with CPMISessionGetServerMajorVersion, CPMIGetMajorReleaseVer and CPMIGetMinorReleaseVer to determine if the application will run properly with current CPMI client and server versions.

Prototypecpresult CPMISessionGetServerMajorVersion (OpsecSession * pSession,

unsigned int * pMinorVer);

Table 3-20 CPMISessionGetServerMajorVersion arguments

argument meaning

pSession A valid and bounded OPSEC Session

pTimeout The address of an unsigned int variable that receives the server major version.

CPMI Requests

76

Argument

Return Value


CPMISessionGetServerHAMode

CPMISessionGetServerHAMode retreives the High Availablitiy mode of the CPMI server.

Prototypecpresult CPMISessionGetServerHaMode (OpsecSession * pSession,

tCPMI_SERVER_HA_MODE * pMode);

Argument

Return Value


CPMISessionGetServerType

CPMISessionGetServerType retrieves the type of the server, such as a SmartCenter Server, Customer Management Add-on Management, Provider-1/SiteManager-1 etc.

PrototypeCPMI_C_API cpresult CPMISessionGetServerType (OpsecSession * pSession,

tCPMI_SERVER_TYPE * pType);

Table 3-21 CPMISessionGetServerMinorVersion arguments

argument meaning


pTimeout The address of an unsigned int variable that receives the server minor version.

Table 3-22 CPMISessionGetServerHaMode arguments

argument meaning


pmode The address of a tCPMI_SERVER_HA_MODE variable to receive the HA mode.

CPMI Requests


Argument

Return Value


CPMISessionGetServerRunType

CPMISessionGetServerRunType retrieves the server run type.

Examples

eCPMI_SERVER_RUN_TYPE_SECONDARY = this SmartCenter Server is a secondary server

eCPMI_SERVER_RUN_TYPE_PRIMARY = this SmartCenter Server is a primary server

Prototypecpresult CPMISessionGetServerRunType (OpsecSession * pSession,

tCPMI_SERVER_RUN_TYPE * pType);

Argument

Return Value


CPMISessionGetServerInstallType

CPMISessionGetServerInstallType retreives the server installation type.

Table 3-23 CPMISessionGetServerType arguments

argument meaning


pType The address of a tCPMI_SERVER_HA_MODE variable to receive the server type.

Table 3-24 CPMISessionGetServerRunType arguments

argument meaning

pSession A valid and bounded OPSEC session.

pType The address of a tCPMI_SERVER_RUN_TYPE variable to receive the server type.

CPMI Requests

78

Example

eCPMI_SERVER_INSTALL_TYPE_MGMT_MODULE = "enterprise" installation (management and module)

eCPMI_SERVER_INSTALL_TYPE_MGMT_ONLY = only the SmartCenter Server

Prototypecpresult CPMISessionGetServerInstallType (OpsecSession * pSession,

tCPMI_SERVER_INSTALL_TYPE * pType);

Argument

Return Value


CPMISessionGetServerSPVersion

CPMISessionGetServerSPVersion retrieves the server-side service pack version number.

Prototypecpresult CPMISessionGetServerSPVersion (OpsecSession * pSession,

unsigned int * pSPVer);

Argument

Return Value


Table 3-25 CPMISessionGetServerInstallType arguments

argument meaning


pType The address of a tCPMI_SERVER_INSTALL_TYPE variable to receive the server type.

Table 3-26 CPMISessionGetServerSPVersion arguments

argument meaning

pSession A valid and bounded Session

pSPVer Address of an unsigned int variable to receive the server service pack version.

CPMI Requests


CPMISessionGetServerHFVersion

CPMISessionGetServerHFVersion retrieves the server-side hotfix version number.

Prototypecpresult CPMISessionGetServerHFVersion (OpsecSession * pSession,

unsigned int * pHFVer);

Argument

Return Value


CPMISessionGetServerBuildNumber

CPMISessionGetServerBuildNumber retreives the server-side build number.

Prototypecpresult CPMISessionGetServerBuildNumber (OpsecSession * pSession, unsigned int * pBuild);

Argument

Return Value


Table 3-27 CPMISessionGetServerHFVersion arguments

argument meaning


pHFVer Address of an unsigned int variable to receive the server hotfix version.

Table 3-28 CPMISessionGetServerBuildNumber arguments

argument meaning


pBuild Address of an unsigned int variable to receive the server build number.

Databases

80

CPMISessionIsSmcBackup

CPMISessionIsSmcBackup retrieves if the server is an SMC Backup server.

Prototypecpresult CPMISessionIsSmcBackup (OpsecSession * pSession);

Argument

Return Value

CP_S_OK, CP_S_FALSE or some error

DatabasesThis section describes functions that manage databases.

In This Section

Database ManagementThe functions described in this section enable you to open, close and create new objects on databases. Return value error codes are listed on page 212.

In This Section

Table 3-29 CPMISessionIsSmcBackup arguments

argument meaning


Database Management page 80

Getting Database Properties page 82

Database Iteration page 86

CPMIDbOpen page 81

CPMIDbClose page 81

Databases


CPMIDbOpen

CPMIDbOpen opens the requested database.This database must be closed later using CPMIDbClose (see page 81) before it can be re-opened.

Prototypecpresult CPMIDbOpen (OpsecSession *pSession,

const char *szDBname,tCPMI_DB_OPEN_MODE openMode, CPMIDb_CB pfnCB, void *pvOpaque,cpmiopid *pOpid);

Arguments

Return Values

CP_S_OK if successful.

CP_E_INVALIDARG, or CPMI_E_OPSEC_SESSION.

CPMIDbClose

CPMIDbClose closes the specified database and decrements the handle reference count. The database handle should not be released after the call to CPMIDbClose

Prototypecpresult CPMIDbClose (HCPMIDB hDb);

Table 3-30 CPMIDbOpen arguments

argument meaning

pSession A pointer to a valid session.

szDBname Database name. Reserved. Must be empty string (““).

openMode Open mode from tCPMI_DB_OPEN_MODE.

pfnCB User function to be called when operation is done.

pvOpaque User-supplied data to be passed to the callback function.

pOpId Address of the cpmiopid variable to be set to the operation ID. On failure, *pOpId is set to CPMIOPID_ERR.

Note - CPMIDbClose should be called before the call to CPMISessionEnd or before the session end handler, otherwise CPMI will call this API.

Databases

82

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE.

Getting Database PropertiesThis section lists functions that return information about the currently open database.

In This Section

CPMIDbGetOpenMode

CPMIDbGetOpenMode retrieves the specified database’s working mode.

Prototypecpresult CPMIDbGetOpenMode (HCPMIDB hDb, tCPMI_DB_OPEN_MODE *pmode);

Table 3-31 CPMIDbClose arguments

argument meaning

hDb A valid CPMI database handle.

CPMIDbGetOpenMode page 82

CPMIDbGetName page 83

CPMIDbGetSession page 83

Databases


Arguments

Return Value


CPMIDbGetName

CPMIDbGetName gets the database name.

Prototypecpresult CPMIDbGetName (HCPMIDB hDb, const char ** pszName);

Arguments

Return Value

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE

CPMIDbGetSession

CPMIDbGetSession gets a pointer to the OPSEC Session used by any given database.

Table 3-32 CPMIDbGetOpenMode arguments

argument meaning

hDb The database handle.

pMode Address of the tCPMI_DB_OPEN_MODE variable to be set to the database’s working mode, one of:

event meaning

eCPMI_DB_OM_READ Read-only. The database may be opened by other clients.

eCPMI_DB_OM_WRITE

Read-write. The database may be opened by other clients.

Table 3-33 CPMIDbGetName arguments

argument meaning


pszName Address of string variable to receive the db name, *pszName is set to NULL on failure. *pszName should not be freed by caller.

Databases

84

Prototypecpresult CPMIDbGetSession (HCPMIDB hDb, OpsecSession **ppSession);

Arguments

Return Values


CPMIDbSetSessionDescription

CPMIDbSetSessionDescription changes the client session description. After calling this function each audit will contain the description in the "Session ID" field.

Prototypecpresult CPMIDbSetSessionDescription(HCPMIDB hDb,const char* szSessionDesc,CPMIDb_CB pfnCb,void* pvOpaque,cpmiopid* pOpId);

Table 3-34 CPMIDbGetSession arguments

argument meaning


ppSession Address of OPSEC Session pointer that receives the OPSEC Session pointer. **ppSession is set to NULL upon failure.

Databases


Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_FAIL

CPMIDbGetObjectDisplayInfo

CPMIDbGetObjectDisplayInfo retrieves relative paths to icons of database objects.

Prototypecpresult CPMIDbGetObjectDisplayInfo(HCPMIDB hDb,tCPMI_OBJECT_DISPLAY_INFO_REQUEST * pRequests,unsigned int nRequestsCount,CPMIObjDispInfo_CB pfnCb,void* pvOpaque,cpmiopid* pOpId);

Table 3-35 CPMIDbSetSessionDescription arguments

argument meaning

hDb Valid CPMI database handle.

szSessionDesc string variable containing the new session description.



pOpid Address of the cpmiopid variable to be set to the operation ID. On failure, *pOpId is set to CPMIOPID_ERR.

Databases

86

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_FAIL

For more details about the parameters of this API, see the CPMISharedDataTypes.h and CPMIClientDataTypes.h files.

Database IterationThe following functions enable you to step through the databases in a session.

In This Section

Table 3-36 CPMIDbGetObjectDisplayInfo arguments

argument meaning

hDb Valid CPMI database handle.

pRequests Array containing the requests for display information.

nRequestsCount

Number of requests for display information.



pOpid Address of the cpmiopid variable to be set to the operation ID. On failure, *pOpId is set to CPMIOPID_ERR.

CPMIDBQueryTables page 87

CPMIDbGetCandidates page 88

enum tagCPMI_CANDIDATE_OPERATION page 88

CPMIAppsInstallPolicy page 89

CPMIAppsUnInstallPolicy page 91

enum tagCPMI_POLICY_INSTALL_OPTION page 92

CPMIDBQueryTablesByContext page 94

CPMISessionIterDb page 95

CPMIIterDbGetNext page 96

CPMIIterDbGetCount page 96

Databases


CPMIDBQueryTables

CPMIDBQueryTables performs multiple queries on multiple tables from one API call, instead of multiple calls to CPMITblQueryObjects.

Prototypecpresult CPMIDBQueryTables (HCPMIDB hDb,

HCPMITBL * hTbls, const char **pszQuerys, unsigned int queryNum, CPMIQuery_CB pfnCB,void * pvOpaque, cpmiopid * pOpID);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_QUERY_SYNTAX, CPMI_E_DB_NOT_OPEN.

CPMIIterDbIsDone page 97

CPMIIterDbIsEmpty page 97

CPMIIterDbRestart page 98

Table 3-37 CPMIDbQueryTables arguments

argument meaning


hTbls An array of table handles.

pszQuery An array of query strings. Use NULL on each query string in order to get all objects.

queryNum Number of table handles (and query strings) in the arrays.

pfnCB User function to be called when the operation is done.


pOpId The address of the cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure. (for an explanation of operation id see TABLE 3-152)

Databases

88

CPMIDbGetCandidates

CPMIDbGetCandidates retrieves the candidates according to the opType operation. The application objects handles (HCPMIAPP) can be retrieved from the resulting objects using “CPMIObjGetAppHandle” on page 139.

Prototypecpresult CPMIDbGetCandidates (HCPMIDB hDb , tCPMI_CANDIDATE_OPERATION opType, unsigned int nAppType, CPMIQuery_CB pfnCB, void * pvOpaque , cpmiopid * pOpId);

Arguments

Return Values


enum tagCPMI_CANDIDATE_OPERATION

Declarationtypedef enum{

tagCPMI_CANDIDATE_OPERATION tCPMI_CANDIDATE_OPERATION;}(CPMISharedDataTypes.h)

and

typedef enum {tagCPMI_APP_TYPE tCPMI_APP_TYPE;

Table 3-38 CPMIDbGetCandidates arguments

argument meaning


opType Indicates to the operation type.

nAppType OR'ed of tag CPMI_APP_TYPE. (see “tagCPMI_APP_TYPE Enumerations” on page 89)

pfnCB The user function to be called when the operation is done.


pOpId Address of cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure.

Databases


}(CPMISharedDataTypes.h)

Enumerations

CPMIAppsInstallPolicy

CPMIAppsInstallPolicy installs a policy on an array of an application object. The user function will be called separately for every application object from the application array reporting its state and status.

Note - tagCPMI_APP_TYPE tCPMI_APP_TYPE are interchangeable

Table 3-39 tagCPMI_APP_TYPE Enumerations

member meaning binary equivalent

eCPMI_CO_INSTALL 0x0

eCPMI_AT_FW1 Firewall-1 application 0x00000001

eCPMI_AT_FG1 Floodgate-1 application 0x00000002

eCPMI_AT_OPSEC OPSEC application 0x00000004

eCPMI_AT_HA HighAvailability application 0x00000008

eCPMI_AT_VPN1 VPN-1 application 0x00000010

eCPMI_AT_OS OS application (cpshared) 0x00000020

eCPMI_AT_MANAGEMENT

management application 0x00000040

eCPMI_AT_WAM WAM (WebAccess Manager) application

0x00000080

eCPMI_AT_LOGSERVER

log server application 0x00000100

eCPMI_AT_DTPS desktop policy server application

0x00000200

eCPMI_AT_WAC WAC application 0x00000400

eCPMI_AT_OSE OSE device application 0x00000800

eCPMI_AT_VPN_NET VPN dedicate application 0x00001000

Databases

90

Prototype

cpresult CPMIAppsInstallPolicy (HCPMIAPP* pApps,

unsigned int nAppsCount,

const char* szPolicyName,

unsigned int nInstallOptions,

unsigned int nInstallOptionsEx,

CPMIPolicyInstall_CB pfnCB,

void* pvOpq,

cpmiopid* pOpid);

Databases


Arguments

Return Values


CPMIAppsUnInstallPolicy

CPMIAppsUnInstallPolicy uninstalls a policy from an array of application objects. The user function will be called separately for every application object from the application array and reports its state and status.

Table 3-40 CPMIAppsInstallPolicy arguments

arguments meanings

pApps Array of application objects to install on

nAppsCount Number of applications in pApps (size of pApps)

szPolicyName The name of the policy object.

nInstallOptions OR'ed combination from tCPMI_POLICY_INSTALL_OPTION.

nInstallOptionsEx For Future use. Currently being ignored.



pOpId Address of cpmiopid variable to receive the operation id. *pOpId is set to 0 upon failure.

uninstall arguments uninstall meanings

pApps Array of application objects to uninstall from.

nAppsCount Number of applications in pApps (size of pApps)

szPolicyName The name of the policy object.





pOpId Address of cpmiopid variable to receive the operation id. *pOpId is set to 0 upon failure.

Databases

92

Prototypecpresult CPMIAppsUnInstallPolicy (HCPMIAPP* pApps, unsigned int appsCount, unsigned int nUnInstallOptions, unsigned int nUnInstallOptionsEx, CPMIPolicyInstall_CB pfnCB, void * pvOpq, cpmiopid * pOpid);

Arguments

Return Values

return CP_S_OK, CP_E_INVALIDARG, and case specific error codes

enum tagCPMI_POLICY_INSTALL_OPTION

Declarationtypedef enum {

tagCPMI_POLICY_INSTALL_OPTION tCPMI_POLICY_INSTALL_OPTION;

Table 3-41 CPMIAppsUnInstallPolicy arguments

argument meaning

pApps Array of application objects to uninstall from.

nAppsCount Number of applications in pApps (size of pApps).






Databases


}

Callback

The user function will be called separately for every application object from the application array.

Declarationtypedef eOpsecHandlerRC (*pfnCPMIPolicyInstall_CB) (HCPMIDB hDb,HCPMIREF refApp,tCPMI_POLICY_INSTALL_STATE state, cpresult stateResult, const char* szMessage,cpresult isLast,cpmiopid opid,void * pvQpq);.

Table 3-42 enum tagCPMI_POLICY_INSTALL_OPTION Enumerations

member meaning binary

equivalent

eCPMI_PIO_ALL_OR_NONE Used to indicate that the policy installation operation should behave as all-or-none.

0x1

eCPMI_PIO_ALL_OR_NONE_CLUSTER

Used to indicate that the policy installation operation should behave as all-or-none with regard to clusters.

0x2

eCPMI_PIO_VALIDATION_ONLY Used to indicate that the policy installation operation should only do policy validation.

0x4

Table 3-43 eOpsecHandlerRC Callback

parameter meaning

hDb The handle to the database where the installation has occurred.

refApp Reference to the application for which there is a report.

state The installation state of hApp.

stateResult The result for state.

Databases

94

CPMIDBQueryTablesByContext

CPMIDBQueryTablesByContext performs multiple queries from multiple tables with context reduction. This can replace separate calls to CPMITblQueryObjectsByContext. For more information on CPMITblQueryObjectsByContext see page 111.

Prototypecpresult CPMIDBQueryTablesByContext (HCPMIDB hDb,

HCPMITBL * hTbls, const char **pszQuerys, HCPMICONTEXT* hContexts, unsigned int queryNum, CPMIQuery_CB pfnCB, void * pvOpaque, cpmiopid * pOpID);

zMessage The extended string message.

isLast Is last notification for this state (CP_S_OK or CP_S_FALSE).

paramopid operation id as was returned from CPMIAppsInstallPolicy/CPMIAppsUninstallPolicy.

parampvOpq User data as was passed to CPMIAppsInstallPolicy/CPMIAppsUninstallPolicy.

Table 3-43 eOpsecHandlerRC Callback

parameter meaning

Databases


Arguments

Return Values

CP_S_OK if succeeded, CP_E_INVALIDARG if the output argument pOpId is invalid or if the arrays are 0 size, CP_E_HANDLE if a NULL database handle or any NULL table handle in the array was passed, CPMI_E_QUERY_SYNTAX if any query has invalid syntax or some unexpected error occurs (for further information see “Function Return Values” on page 34).

CPMISessionIterDb

CPMISessionIterDb gets an iteration handle to iterate over the opened databases on a given session.

Prototypecpresult CPMISessionIterDb (OpsecSession * pSession, HCPMIITERDB * phIter);

Table 3-44 CPMIDbQueryTablesByContext arguments

argument meaning


hTbls An array of table handles.

pszQuery An array of query strings. Use NULL on each query string in order to get all objects.

hContexts An array of context handles.

queryNum Number of table handles (and query strings) in the arrays.




Databases

96

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG.

CPMIIterDbGetNext

CPMIIterDbGetNext retrieves a handle to the next database in the session, if this is the first call to the function, the first database handle is retrieved.

Prototypecpresult CPMIIterDbGetNext (HCPMIITERDB hIter, HCPMIDB *phDb);

Arguments

Return Values


CPMIIterDbGetCount

CPMIIterDbGetCount retrieves the number of databases on the current iteration.

Prototypecpresult CPMIIterDbGetCount (HCPMIITERDB hIter, unsigned int *pCount);

Table 3-45 CPMISessionIterDB arguments

argument meaning

pSession OpsecSession used in opening the databases

phIter Handle to database iteration object. *phIter is set to NULL upon failure. *phIter should be released with CPMIHandleRelease when no longer needed.

Table 3-46 CPMIiterDbGetNext arguments

argument meaning

hIter The database iterator handle.

phDb The address of the HCPMIDB variable to be set to the database handle. When done, On failure *phDb is set to NULL. *phDb should be released when no longer needed.

Databases


Arguments

Return Values


CPMIIterDbIsDone

CPMIIterDbIsDone checks if the iteration has been completed.

Prototypecpresult CPMIIterDbIsDone (HCPMIITERDB hIter);

Arguments

Return Values

CP_S_OK, CP_S_FALSE, CP_E_HANDLE.

CPMIIterDbIsEmpty

CPMIIterDbIsEmpty checks if the database iteration object is empty.

Prototypecpresult CPMIIterDbIsEmpty (HCPMIITERDB hIter);

Table 3-47 CPMIIterDbGetCount arguments

argument meaning


pCount The address of the unsigned int variable to be set to the number of databases. *pCount is set to -1 on failure.

Table 3-48 CPMIIterDbIsDone arguments

argument meaning


Databases

98

Arguments

Return Values


CPMIIterDbRestart

CPMIIterDbRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterDbRestart (HCPMIITERDB hIter);

Arguments

Return Values

CP_S_OK, CP_E_HANDLE.

Table 3-49 CPMIIterDbIsEmpty arguments

argument meaning

hIter The database iteration handle.

Table 3-50 CPMIIterDbRestart arguments

argument meaning


Tables


TablesThis section describes functions that manage database tables.

In This Section

Table PropertiesThe functions described below extract information from tables.

In This Section

CPMIDbGetTable

CPMIDbGetTable gets a table from the database. Release the table with CPMIHandleRelease (see page 62) when not needed anymore.

Prototypecpresult CPMIDbGetTable (HCPMIDB hDb,

const char * szTblName, HCPMITBL * phTbl);

“Table Properties” on page 99

“Table Iteration” on page 102

CPMIDbGetTable page 99

CPMITblGetDB page 100

CPMITblGetName page 100

CPMITblGetDisplayString page 101

CPMITblIsWriteable page 101

Tables

100

Arguments

Return Value

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_TBL_NOT_FOUND.

CPMITblGetDB

CPMITblGetDB retrieves the handle of the “parent” database of the given table.

Prototypecpresult CPMITblGetDB (HCPMITBL hTbl, HCPMIDB *pDb);

Arguments

Return Values


CPMITblGetName

CPMITblGetName retrieves the name of the table.

Prototypecpresult CPMITblGetName (HCPMITBL hTbl, const char **psz);

Table 3-51 CPMIDbGetTable arguments

argument meaning


szTblName Name of table to get.

phTbl Address of HCPMITBL receive the table handle. *phTbl is set to NULL upon failure. *phTbl should be released when no longer needed.

Table 3-52 CPMITblGetDB arguments

argument meaning

hTbl The table handle.

pDb The address of the HCPMIDB variable to be set to the database handle. On failure, *pDb is set to NULL. *pDb should be released when no longer needed.

Tables


Arguments

Return Values


CPMITblGetDisplayString

CPMITblGetDisplayString returns the table display string.

Prototyperesult CPMITblGetDisplayString (HCPMITBL hTbl, const char ** pszDisplayStr);

Arguments

Return Values


CPMITblIsWriteable

CPMITblIsWriteable checks for table working mode (read-only or read-write).

Prototypecpresult CPMITblIsWriteable (HCPMITBL htbl);

Table 3-53 CPMITblGetName arguments

argument meaning


psz The address of a string variable to be set to the table name. On failure, *psz is set to NULL. *psz should not be released.

Table 3-54 CPMITblGetDisplayString arguments

argument meaning

hTbl handle to table

pszDisplayStr The address of a string variable to be set to the table name. On failure, *psz is set to NULL. *psz should not be released.

Tables

102

Arguments

Return Value

CP_S_OK indicate read-write mode,

CP_S_FALSE indicate read-only mode,

CP_E_HANDLE on failure.

Table IterationThe following functions enable you to step through the tables in a database.

In This Section

CPMIDbIterTables

CPMIDbIterTables gets an iteration handle to iterate over the database tables. Release the HCPMIITERTBL variable with CPMIHandleRelease (see page 62) when not needed anymore.

Prototypecpresult CPMIDbIterTables (HCPMIDB hDb, HCPMIITERTBL * phIter);

Table 3-55 CPMITblGetName arguments

argument meaning


CPMIDbIterTables page 102

CPMIIterTblGetCount page 103

CPMIIterTblGetNext page 103

CPMIIterTblIsDone page 104

CPMIIterTblIsEmpty page 104

CPMIIterTblRestart page 105

CPMITblGetObjectCount page 105

Tables


Arguments

Return Values


CPMIIterTblGetCount

CPMIIterTblGetCount retrieves the number of tables in the given database.

Prototypecpresult CPMIIterTblGetCount (HCPMIITERTBL hIter, unsigned int *pCount);

Arguments

Return Values


CPMIIterTblGetNext

CPMIIterTblGetNext retrieves a handle to the next table in the database, if this is the first call to the function, the first table handle is retrieved. When no longer needed, this handle should be freed using CPMIHandleRelease (see page 62).

Table 3-56 CPMIDbIterTables arguments

argument meaning


phIter Address of HCPMIITERTBL to receive the table iteration handle. *phIter is set to NULL upon failure. *phIter should be released when no longer needed.

Table 3-57 CPMIIterTblGetCount arguments

argument meaning

hIter The handle to a table iteration object.

pCount The address of the unsigned int variable to be set to the number of tables. On failure, *pCount is set to ((unsigned int)-1).

Tables

104

Prototypecpresult CPMIIterTblGetNext (HCPMIITERTBL hIter, HCPMITBL *phTbl);

Arguments

Return Values


CPMIIterTblIsDone

CPMIIterTblIsDone tests whether the iteration has been completed.

Prototypecpresult CPMIIterTblIsDone (HCPMIITERTBL hIter);

Arguments

Return Values


CPMIIterTblIsEmpty

CPMIIterTblIsEmpty checks whether the table is empty of objects.

Prototypecpresult CPMIIterTblIsEmpty (HCPMIITERTBL hIter);

Table 3-58 CPMIIterTblGetNext arguments

argument meaning


phTbl The address of the HCPMITBL variable to be set to the handle of the next table. On failure, *phTbl is set to NULL.*phTbl should be released when no longer needed.

Table 3-59 CPMIIterTblIsDone arguments

argument meaning


Tables


Arguments

Return Values


CPMIIterTblRestart

CPMIIterTblRestart starts the iteration over from beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterTblRestart (HCPMIITERTBL hIter);

Arguments

Return Values


CPMITblGetObjectCount

CPMITblGetObjectCount get number of objects of a given table.

Prototypecpresult CPMITblGetObjectCount (HCPMITBL hTbl,

CPMIGetCount_CB pfnCB, unsigned int nFlags,void * pvOpaque,cpmiopid * pOpId);

Table 3-60 CPMIIterTblIsEmpty arguments

argument meaning


Table 3-61 CPMIIterTblReStart arguments

argument meaning


Objects

106

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG,CP_E_UNEXPECTED,CP_E_HANDLE

ObjectsThis section describes functions that manage CPMI objects.

In This Section

Managing Objects in TablesThe following functions manage objects in tables.

In This Section

Table 3-62 CPMITblGetObjectCount arguments

argument meaning



nFlags Unused. Should be 0 (zero).


pOpId The address of the cpmiopid variable to receive the operation id.

Managing Objects in Tables page 106

Querying Objects in Tables page 110

General Object Management page 114

CPMITblGetObj page 107

CPMITblGetObjByContext page 107

CPMITblDeleteObj page 108

CPMIObjIsReduced page 109

Objects


CPMITblGetObj

CPMITblGetObj gets an object from a table.

Prototypecpresult CPMITblGetObj (HCPMITBL hTbl,

const char * szObjName, CPMIObj_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_INVALIDARG, CPMI_E_DB_NOT_OPEN

CPMITblGetObjByContext

CPMITblGetObjByContext gets an object from a table with context reduction, i.e. only fields approved by the context remain in the result object.

Prototypecpresult CPMITblGetObjByContext (HCPMITBL hTbl,

const char * szObjName, CPMIObj_CB pfnCB, void * pvOpaque, HCPMICONTEXT hContext, cpmiopid * pOpId);

Table 3-63 CPMITblGetObj arguments

argument meaning


szObjName The name of object to get.


pvOpaque The user data to pass to pfnCB.


Objects

108

Arguments

Return Values

CP_S_OK if succeeded, CPMI_E_DB_NOT_OPEN if the database will not open, CP_E_INVALIDARG if the object name is empty or the output argument pOpId is invalid, CP_E_HANDLE if a NULL table handle was passed or some unexpected error occurs (for further information see “Function Return Values” on page 34).

CPMITblDeleteObj

CPMITblDeleteObj deletes an object from a given table.

Prototypecpresult CPMITblDeleteObj (HCPMITBL hTbl,

const char * szObjName, CPMIDB_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Table 3-64 CPMITblGetObjByContext arguments

argument meaning


szObjName The name of object to get.



hContext The Context handle.


Objects


Arguments

Return Values


CPMIObjIsReduced

CPMIObjIsReduced checks to see if the object is currently reduced due to context reduction. For more information on context and context reduction see “CPMI Context Objects” on page 40.

Prototypecpresult CPMIObjIsReduced (HCPMIOBJ hObj);

Arguments

Return Values

CP_S_OK if succeeded, CP_E_HANDLE if a NULL reference handle was passed.

CPMIDbServerValidateObjects

CPMIDbServerValidateObjects validate several objects at one api call.

Table 3-65 CPMITblDeleteObj arguments

argument meaning


szObjName The name of the object to be deleted.




Table 3-66 CPMITblDeleteObj arguments

argument meaning

hObj The object handle.

Objects

110

Prototypecpresult CPMIDbServerValidateObjects(HCPMIDB hDb, HCPMIOBJ * arrObjects, unsigned int nNumObjects, unsigned int nFlags, CPMIDb_Ex pfnCB, void * pvOpq, cpmiopid * pOpId);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG,CP_E_HANDLE, and case specific error codes

Querying Objects in TablesThe functions below query a table and enable you to retrieve the query’s results. For the query syntax see “Queries” on page 45.

In This Section

Table 3-67 CPMIDbServerValidateObjects arguments

argument meaning

hDb handle to the database object

arrObjects array of handles to objects

nNumObjects num of elements in arrObjects


nFlags Unused. Should be 0 (zero).

pvOpq User data to pass to pfnCB.


CPMITblQueryObjects page 111

CPMITblQueryObjectsByContext page 111

CPMIResultIterObj page 112

Objects


CPMITblQueryObjects

CPMITblQueryObjects querys a given table for objects.

Prototypecpresult CPMITblQueryObjects (HCPMITBL hTbl,

const char * szQuery, CPMIQuery_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_QUERY_SYNTAX.

CPMITblQueryObjectsByContext

CPMITblQueryObjectsByContext querys a given table for objects with context reduction, only fields approved by the context will remain in each object in the result.

Table 3-68 CPMITblQueryObjects arguments

argument meaning


szQuery The Query string. use NULL to get all objects.




Objects

112

Prototypecpresult CPMITblQueryObjectsByContext (HCPMITBL hTbl,

const char * szQuery, CPMIQuery_CB pfnCB, void * pvOpaque, HCPMICONTEXT hContext, cpmiopid * pOpId);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_QUERY_SYNTAX if the query has invalid syntax or some unexpected error occurs (for further information see “Function Return Values” on page 34).

CPMIResultIterObj

CPMIResultIterObj gets an iteration handle to iterate over the objects on a given query result. Release the HCPMIITEROBJ variable with CPMIHandleRelease (see page 62) when not needed anymore.

Prototypecpresult CPMIResultIterObj (HCPMIRSLT hRes, HCPMIITEROBJ *phIter);

Table 3-69 CPMITblQueryObjectsByContext arguments

argument meaning


szQuery The Query string. use NULL to get all objects.





Objects


Arguments

Return Values


CPMIQueryCreate

CPMIQueryCreate creates a query object for a given query syntax

Prototypecpresult CPMIQueryCreate (const char * szQuerySyntax,

HCPMITBL hTbl, HCPMIQUERY * phQuery);

Arguments

Return Values


CPMIObjQueryApply

CPMIObjQueryApply apply a query on object

Prototypecpresult CPMIObjQueryApply (HCPMIOBJ hObj,

HCPMIQUERY hQuery);

Table 3-70 CPMIResultIterObj arguments

argument meaning

hRes A handle to the query results.

phIter The address of the HCPMIITEROBJ variable to be set to the iterator handle. On failure, *phIter is set to NULL.*phIter should be released when no longer needed.

Table 3-71 CPMIQueryCreate arguments

argument meaning

szQuerySyntax Query string

hTbl Handle to table.

phQuery Address of HCPMIQUERY variable to receive the Query object.

Objects

114

Arguments

Return Values


General Object ManagementThe following functions enable you to create, save, delete, lock and validate objects.

In This Section

Table 3-72 CPMIObjQueryApply arguments

argument meaning

hObj Handle to object.

hQuery Handle to query object.

CPMIDbCreateObject page 115

CPMIObjIsDeletable page 116

CPMIObjDelete page 116

CPMIDbDeleteObjByRef page 117

CPMIObjUpdate page 117

CPMIObjAcquireLock page 118

CPMIDbAcquireLockByRef page 119

CPMIObjReleaseLock page 120

CPMIDbReleaseLockByRef page 120

CPMIObjValidateEx page 121

CPMIObjValidateName page 121

CPMIObjValidateField page 122

CPMIObjResetFieldByName page 123

CPMIObjResetField page 123

CPMIObjResetFieldByName page 123

CPMIObjIsRenameable page 124

CPMIObjSetName page 124

CPMIObjGetName page 125

Objects


CPMIDbCreateObject

CPMIDbCreateObject creates a new object on the database.

Prototypecpresult CPMIDbCreateObject (HCPMIDB hDb,

const char * szObjType, CPMIObj_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Arguments

Return Value

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_DB_NOT_OPEN.

CPMIObjGetDb page 125

CPMIObjGetTbl page 126

CPMIObjGetUID page 126

CPMIObjGetClass page 127

CPMIObjIsOfClass page 127

CPMIObjGetLastModifier page 128

CPMIObjGetLastModifierHost page 128

CPMIObjGetLastModificationTime page 129

CPMIObjGetReferrals page 129

CPMIObjIsOwned page 130

CPMIObjClone page 131

Table 3-73 CPMIDbCreateObject arguments

argument meaning


szObjType Type of object to create (from the Schema).



pOpId The address of the cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure. (for an explanation of operation id see TABLE 3-152).

Objects

116

CPMIObjIsDeletable

CPMIObjIsDeletable checks whether an object may be deleted.

Prototypecpresult CPMIObjIsDeletable (HCPMIOBJ hObj);

Arguments

Return Values


CPMIObjDelete

CPMIObjDelete deletes the specified object.

Prototypecpresult CPMIObjDelete (HCPMIOBJ hObj,

CPMIObj_CB pfnCB, void *pvOpaque,cpmiopid *pOpId);

Arguments

Return Values


Table 3-74 CPMIObjIsDeletable arguments

argument meaning


Table 3-75 CPMIObjDelete arguments

argument meaning


pfnCB The function to be called once the object has been deleted. For more information see “CPMIObj_CB””.



Objects


CPMIDbDeleteObjByRef

CPMIDbDeleteObjByRef deletes the referenced object from the database.

Prototypecpresult CPMIDbDeleteObjByRef (HCPMIOBJ hDb,

HCPMIREF hRef, CPMIDb_CB pfnCB, void *pvOpaque, cpmiopid *pOpId);

Arguments

Return Values


CPMIObjUpdate

CPMIObjUpdate updates the specified object in the database.

Prototypecpresult CPMIObjUpdate (HCPMIOBJ hObj,

CPMIDb_CB pfnCB, void *pvOpaque,cpmiopid *pOpId);

Table 3-76 CPMIObjDelete arguments

argument meaning

hDb Handle to the database where the referenced object resides.

hRef The referenced handle.

pfnCB The User function to be called when the operation is done.


pOpId The address of the cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure.

Objects

118

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_DB_NOT_OPEN, CP_E_FAIL.

CPMIObjAcquireLock

CPMIObjAcquireLock guarantees exclusive access to an object by locking it. When an object is locked, all its attributes, owned, linked, and member objects are locked as well.

Prototypecpresult CPMIObjAcquireLock (HCPMIOBJ hObj,

CPMIDb_CB pfnCB, void *pvOpaque,cpmiopid *pOpId);

Table 3-77 CPMIObjUpdate arguments

argument meaning


pfnCB The function to be called once the object has been updated. For more information, see “CPMIDb_CB””.



Note - If the given hObj is a new object that hasn’t been updated, the error code CPMI_E_OBJ_LOCK is returned immediately and pfnCB is not called.

Objects


Arguments

Return Values


CPMIDbAcquireLockByRef

CPMIDbAcquireLockByRef attempts to aquire a lock on a given referenced object. Guarantees exclusive access to an object by locking it.

Prototypecpresult CPMIDbAcquireLockByRef (HCPMIDB hDb,

HCPMIREF hRef, CPMIQuery_CB pfnCB, void *pvOpaque, cpmiopid *pOpId);

Arguments

Table 3-78 CPMIObjAcquireLock arguments

argument meaning


pfnCB The function to be called once the object has been locked. For more information, see “CPMIDb_CB”.



Table 3-79 CPMIDbAcquireLockByRef arguments

argument meaning


hRef The referenced handle.



pOpId Address of cpmiopid variable to receive the operation id.On failure, *pOpId is set to CPMIOPID_ERR.

Objects

120

Return Values


CPMIObjReleaseLock

CPMIObjReleaseLock unlocks an object locked by CPMIObjAcquireLock.

Prototypecpresult CPMIObjReleaseLock (HCPMIOBJ hObj);

Arguments

Return Values


CPMIDbReleaseLockByRef

CPMIDbReleaseLockByRef attempts to release locking on a given referenced object.

Prototypecpresult CPMIDbReleaseLockByRef (HCPMIDB hDb, HCPMIREF hRef);

Arguments

Return Values


Table 3-80 CPMIObjReleaseLock arguments

argument meaning


Table 3-81 CPMIDbReleaseLockByRef arguments

argument meaning


hRef The referenced object handle.

Objects


CPMIObjValidateEx

CPMIObjValidateEx validates that all of an object's fields have a valid value. When validation fails, a descriptive string with the reason for failure is available by calling CPMIDbGetExtendedErrorMessage.

Prototypecpresult CPMIObjValidateEx (HCPMIOBJ hObj , CPMIDb_CB pfnCB , void * pvOpaque , cpmiopid * pOpId);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_DB_NOT_OPEN, CP_E_FAIL

CPMIObjValidateName

CPMIObjValidateName validates an object name. Upon failure, *pszMsg contains the error message. pszMsg should then be release with CPMIFreeString.

Prototypecpresult CPMIObjValidateName (HCPMIOBJ hObj,char ** pszMsg);

Table 3-82 CPMIObjValidateEx arguments

argument meaning


pfnCB The function to be called once the object has been validated.


pOpId The address of the cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure.

Objects

122

Arguments

Return Values

None.

CPMIObjValidateField

CPMIObjValidateField validates an object's specific field value.

Prototypecpresult CPMIObjValidateField (HCPMIOBJ hObj, HCPMIFLD hFld);

Arguments

Return Values

return CP_S_OK, CP_S_FALSE, CP_E_INVALIDARG, CP_E_HANDLE

CPMIObjValidateFieldByName

CPMIObjValidateFieldByName validates an object's specific field value.

Prototypecpresult CPMIObjValidateFieldByName (HCPMIOBJ hObj, const char* szFldName);

Table 3-83 CPMIObjValidateName arguments

argument meaning


Table 3-84 CPMIObjValidateField arguments

argument meaning


hFld The handle to the field to validate.

Objects


Arguments

Return Values

return CP_S_OK, CP_S_FALSE, CP_E_INVALIDARG, CP_E_HANDLE

CPMIObjResetField

CPMIObjResetField restores the field value to its default.

Prototype cpresult CPMIObjResetField (HCPMIOBJ hObj, HCPMIFLD hFld);

Arguments

Return Values

CP_S_OK, CP_E_FAIL, CP_E_INVALIDARG, CPMI_E_HANDLE

CPMIObjResetFieldByName

CPMIObjResetFieldByName restores the field value to its default.

Prototype

cpresult CPMIObjResetFieldByName (HCPMIOBJ hObj,

const char* szFldName);

Table 3-85 CPMIObjValidateFieldByName arguments

argument meaning


szFldName The name of the field to validate

Table 3-86 CPMIObjResetField arguments

arguments meaning


szFldName The handle of the field.

Objects

124

Arguments

Return Values

return CP_S_OK, CP_E_FAIL, CP_E_INVALIDARG, CPMI_E_HANDLE */

CPMIObjIsRenameable

CPMIOBJisRenameable checks to see if the object can be renamed.

Prototype

cpresult CPMIObjIsRenameable (HCPMIOBJ hObj);

Arguments

Return Values

return CP_S_OK if the object is renameable, CP_S_FALSE otherwise.

CPMIObjSetName

CPMIObjSetName sets the name of an object. Fail is the object is not renameable. This can be checked by running “CPMIObjIsRenameable”.

Prototypecpresult CPMIObjSetName (HCPMIOBJ hObj, const char* szObjName);

Table 3-87 CPMIObjResetFieldByName arguments

arguments meaning


szFldName The object handle.

Table 3-88 CPMIObjIsRenameable arguments

arguments meaning


Objects


Arguments

Return Values

CP_S_OK, CP_E_HANDLE, CP_E_FAIL.

CPMIObjGetName

CPMIObjGetName retrieves the name of the designated object.

Prototypecpresult CPMIObjGetName (HCPMIOBJ hObj, const char **psz);

Arguments

Return Values


CPMIObjGetDb

CPMIObjGetDb retrieves a handle to the “parent” database of the object.

Prototypecpresult CPMIObjGetDb (HCPMIOBJ hObj, HCPMIDB *phDb);

Table 3-89 CPMIObjSetName arguments

argument meaning


szObjName The object name to be set.

Table 3-90 CPMIObjGetName arguments

argument meaning


psz The address of a string variable which receives the object name. On failure, *psz is set to NULL. *psz should not be freed.

Objects

126

Arguments

Return Values


CPMIObjGetTbl

CPMIObjGetTbl retrieves a handle to the “parent” table of the object.

Prototypecpresult CPMIObjGetTbl (HCPMIOBJ hObj, HCPMITBL *phTbl);

Arguments

Return Values


CPMIObjGetUID

CPMIObjGetUID retrieves the object’s unique ID.

Prototypecpresult CPMIObjGetUID (HCPMIOBJ hObj, tCPMI_UID *pUID);

Table 3-91 CPMIObjGetDb arguments

argument meaning


phDb The address of the HCPMIDB variable to be set to the parent database’s handle. On failure, *phDb is set to NULL. When no longer needed, *phDb should be released using CPMIHandleRelease.

Table 3-92 CPMIObjGetTbl arguments

argument meaning


phTbl The address of the HCPMITBL variable to be set to the parent table’s handle. On failure, *phTbl is set to NULL.When no longer needed, this *phTbl should be released using CPMIHandleRelease (see page 62).

Objects


Arguments

Return Values


CPMIObjGetClass

CPMIObjGetClass retrieves the schema class handle of the given object.

Prototypecpresult CPMIObjGetClass (HCPMIOBJ hObj, HCPIMICLASS *phClass);

Arguments

Return Values


CPMIObjIsOfClass

CPMIObjIsOfClass checks whether the object type matches the specified class.

Prototypecpresult CPMIObjIsOfClass (HCPMIOBJ hObj, const char* szClassName);

Table 3-93 CPMIObjGetUID arguments

argument meaning


pUID The address of the tCPMI_UID variable to be set to the object’s unique ID. On failure *pUID will be assigned a NULL unique ID.

Table 3-94 CPMIObjGetClass arguments

argument meaning


phClass The address of the HCPMICLASS variable to be set to the object’s class. On failure, *phClass is set to NULL. *phClass should be released when no longer needed.

Objects

128

Arguments

Return Values


CPMIObjGetLastModifier

CPMIObjGetLastModifier retrieves the name of the last Administrator who modified the object.

Prototypecpresult CPMIObjGetLastModifier (HCPMIOBJ hObj, const char **psz);

Arguments

Return Values


CPMIObjGetLastModifierHost

CPMIObjGetLastModifyHost retrieves the name of the machine on which the object was last modified.

Prototypecpresult CPMIObjGetLastModifierHost (HCPMIOBJ hObj, const char **psz);

Table 3-95 CPMIObjIsOfClass arguments

argument meaning


szClassName The class name.

Table 3-96 CPMIObjGetLastModifier arguments

argument meaning


psz The address of a string variable which receives the name of the last Administrator to modify the object. On failure, *psz is set to NULL. *psz should not be freed.

Objects


Arguments

Return Values


CPMIObjGetLastModificationTime

CPMIObjGetLastModificationTime retrieves the time the object was last modified.

Prototypecpresult CPMIObjGetLastModificationTime (HCPMIOBJ obj, time_t *pTime);

Arguments

Return Values


CPMIObjGetReferrals

CPMIObjGetReferrals retrieves all the objects of type referral (hObj). The referrals can be deduced from the object handle (HCPMRSLT) being passed to the user function to be called when the operation is completed (pfnCB).

Prototypecpresult CPMIObjGetReferrals (HCPMIOBJ hobj,

CPMIGetReferrals_CB pfnCB, void *pvOpaque,

Table 3-97 CPMIObjGetLastModifierHost arguments

argument meaning


psz The address of a string variable which receives the name of the machine on which the object was last modified. On failure, *psz is set to NULL. *psz should not be freed.

Table 3-98 CPMIObjGetLastModificationTime arguments

argument meaning

obj The object handle.

pTime The address of a time_t variable that receives the last modification time. *pTime is set to ((time_t)0) on failure.

Objects

130

cpmiopid *pOpId);

Arguments

Example

Assume we have a network_object name london. We wish to know where london is being used. CPMIObjGetReferrals will return in it's call back CPMIResult. Iterating on the result we'll see that it contains 2 HCPMIOBJ. Those objects are of type referral. Each describes a referral to london. London has a referral by the opsec application my_opsec_app in table opsec. The reference itself is of type link and located in the field host:

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_DB_NOT_OPEN, CP_E_FAIL

CPMIObjIsOwned

CPMIObjIsOwned checks if the object is an owned object.

Table 3-99 CPMIObjGetReferrals arguments

argument meaning

hobj The object handle for referral you wish to obtain.



pOpId Address of cpmiopid variable receiving operation id. Upon failure *pOpId is set to 0.

( :AdminInfo ( :chkpf_uid ("{490410FD-2D4B-497E-B3E8-FB5EE4F39152}") :ClassName (referral) ) :referral_info ( :0 (host) ) :referral_obj (ReferenceObject :Table (opsec) :Name (my_opsec_app) ) :type (link))

Objects


Prototypecpresult CPMIObjIsOwned (HCPMIOBJ obj);

Arguments

Return Values

CP_S_OK if the object is owned, CP_S_FALSE otherwise, CP_E_HANDLE on error.

CPMIObjClone

CPMIObjClone clones an object, i.e. create a new local copy with a new HCPMIOBJ.

Prototype

cpresult CPMIObjClone (HCPMIOBJ obj, HCPMIOBJ* phOutObj);

Arguments

Return Values


CPMIDbGetServerObj

CPMIDbGetServerObj get the sever.

Table 3-100 CPMIObjIsOwned arguments

argument meaning

hobj The object handle.

Table 3-101 CPMIObjClone arguments

argument meaning


phOutObj The address of an HCPMIOBJ handle which receives the cloned object. *phOutObj set to NULL on failure. *phOutObj should be released when no longer needed.

Objects

132

Prototype

cpresult CPMIDbGetServerObj (HCPMIDB hDb,

unsigned int nFlags,

CPMIObj_CB pfnCB,

void * pvOpaque ,

cpmiopid * pOpId);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG,CP_E_HANDLE, and case specific error codes

CPMIObjGetReferrals

CPMIObjGetReferrals returns a result of objects of class 'referral'. Each 'referral' object in the returned result describe a reference from the input object to other object.

Prototype

cpresult CPMIDbGetObjReferrals (HCPMIDB hDb,

HCPMIREF hObjRef,

CPMIGetReferrals_CB pfnCB,

void * pvOpaque,

cpmiopid * pOpId);

Table 3-102 CPMIDbGetServerObj arguments

argument meaning

hDb Handle to database

nFlags Additional flags. for future use, currently unused.




Objects


Arguments

Return Values

Address of cpmiopid variable to receive the operation id. *pOpId is set to CPMIOPID_ERR upon failure.

CPMIObjGetUidAsString

CPMIObjGetUidAsString returns the object's unique ID as a string. This API provide better performance than using CPMIObjGetUid and CPMIUidToString together.

Prototype

ccpresult CPMIObjGetUidAsString (HCPMIOBJ hObj, const char ** psz);

Arguments

Return Values

@return CP_S_OK

Table 3-103 CPMIObjGetReferrals arguments

argument meaning

HCPMIDB Valid database handle

HCPMIREF A reference to the object on which the operation is performed.




Table 3-104 CPMIObjGetUidAsString arguments

argument meaning

hObj [IN] The object handle.

hObj [OUT] The address of a string variable which receives the object unique ID formatted as a string. On failure, *psz is set to NULL.

Contexts

134

ContextsThis section contains functions which create, add field names to and remove Context Objects. Context Objects are described in “CPMI Context Objects” on page 40.

CPMIContextCreate

CPMIContextCreate creates a Context Object.

Prototypecpresult CPMIContextCreate (const char* szContextType,

HCPMICONTEXT* phContext);

Arguments

Return Values

CP_S_OK if succeeded, CP_E_FAIL if failed (e.g. unknown context type), CP_E_INVALIDARG if the output handle is invalid.

CPMIContextAddField

CPMIContextAddField add a field name to the Context Object.

Prototypecpresult CPMIContextAddField (HCPMICONTEXT hContext, const char* szFieldName);

CPMIContextCreate page 134

CPMIContextAddField page 134

CPMIContextRemoveField page 135

Table 3-105 CPMIContextCreate arguments

argument meaning

szContextType The type of context to create. The supported type is dynamic_context.

phContext The address of the HCPMICONTEXT receiving the result.

Contexts


Arguments

Return Values

CP_S_OK if succeeded, CP_E_HANDLE if a NULL context handle was passed or CP_E_INVALIDARG if no field name was passed.

CPMIContextRemoveField

CPMIContextRemoveField removes a field name from the Context Object.

Prototypecpresult CPMIContextRemoveField (HCPMICONTEXT hContext,

const char* szFieldName);

Arguments

Return Values

CP_S_OK if succeeded, CP_S_FALSE if the field to remove isn’t in the context, CP_E_HANDLE if a NULL context handle was passed or CP_E_INVALIDARG if no field name was passed.

CPMIIterContextGetNext

CPMIIterContextGetNext retrieves the next field in the context.

Prototypecpresult CPMIIterContextGetNext (HCPMIITERCONTEXT hIter, const char ** psz);

Table 3-106 CPMIContextAddField arguments

argument meaning


szFieldName The field name.

Table 3-107 CPMIContextRemoveField arguments

argument meaning


szFieldName The field name.

Contexts

136

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, and case specific error codes

CPMIIterContextGetCount

CPMIIterContextGetCount retrieves the number of elements in the container iteration.

Prototypecpresult CPMIIterContextGetCount (HCPMIITERCONTEXT hIter, unsigned int * pCount);

Arguments

Return Values


CPMIIterContextIsEmpty

CPMIIterContextIsEmpty checks if the container iterator is empty.

Table 3-108 CPMIIterContextGetNext arguments

argument meaning

hIter The handle to the context iterator.

psz The address of a string variable which receives the next field value. On failure, *psz is set to NULL. *psz should not be freed.

Table 3-109 CPMIIterContextGetCount arguments

argument meaning


pCount The address of the unsigned int variable to be set to the number of elements. On failure, *pCount is set to ((unsigned int)-1).

Contexts


Prototypecpresult CPMIIterContextIsEmpty (HCPMIITERCONTEXT hIter);

Arguments

Return Values


CPMIIterContextIsDone

CPMIIterContextIsDone tests whether the iteration has been completed.

Prototypecpresult CPMIIterContextIsDone (HCPMIITERCONTEXT hIter);

Arguments

Return Values


CPMIIterContextRestart

CPMIIterContextRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterContextRestart (HCPMIITERCONTEXT hIter);

Table 3-110 CPMIIterContextIsEmpty arguments

argument meaning


Table 3-111 CPMIIterContextIsDone arguments

argument meaning


Contexts

138

Arguments

Return Values


CPMICntrIterElements

CPMICntrIterElements retrieves a handle to an element iterator object.

Prototypecpresult CPMIContextIterElements (HCPMICONTEXT hContext , HCPMIITERCONTEXT * phIter);

Arguments

Return Values


CPMICntrRemoveAll

CPMICntrRemoveAll removes all elements from the container.

Prototypecpresult CPMICntrRemoveAll (HCPMICNTR hCnt);

Table 3-112 CPMIIterContextRestart arguments

argument meaning


Table 3-113 CPMICntrIterElements arguments

argument meaning

hCnt The container handle.

phIter The address of the HCPMIITERCNTR variable to be set to the element iterator handle. On failure, *phIter is set to NULL. *phIter should be released when done.

Applications


Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CP_E_FAIL

ApplicationsThis section describes functions that manage applications.

In This Section

Application ManagementThe functions described below enable you to create an application object, to retrieve information about the application’s status and the underlying object.

In This Section

CPMIObjGetAppHandle

CPMIObjGetAppHandle creates an application object from HCPMIOBJ.

Prototypecpresult CPMIObjGetAppHandle (HCPMIOBJ hObj, HCPMIAPP * phApp)

Table 3-114 CPMICntrRemoveAll arguments

argument meaning


Application Management page 139

Managing Certificates for an Application page 141

Application Status Retrieval page 146

CPMIObjGetAppHandle page 139

CPMIAppGetObject page 140

CPMIDbQueryApps page 140

Applications

140

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CP_E_FAIL.

CPMIAppGetObject

CPMIAppGetObject retrieves a handle to the underlying object.

Prototypecpresult CPMIAppGetObject (HCPMIAPP hApp, HCPMIOBJ *phObj);

Arguments

Return Values


CPMIDbQueryApps

CPMIDbQueryApps queries the database for all applications of a specified type.

Prototypecpresult CPMIDbQueryApps (HCPMIDB hDb,

unsigned int nAppType,CPMIQuery_CB pfnCB, void * pvOpaque,

Table 3-115 CPMIObjGetAppHandle arguments

argument meaning


phApp The address of an HCPMIAPP variable which receives the application object handle. On failure *phApp is set to NULL. *phApp should be released when no longer needed.

Table 3-116 CPMIAppGetObject arguments

argument meaning

hApp The application handle.

phObj The address of the HCPMIOBJ variable to be set to the object handle. On failure, *phObj is set to NULL. *phObj should be released when no longer needed.

Applications


cpmiopid * pOpId);

Arguments

Return Values CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE.

Managing Certificates for an ApplicationThe functions described in this section enable creation, pushing and revocation of certificates.

In This Section

CPMIAppCreateCertificate

CPMIAppCreateCertificate enables the creation of a new certificate. This function initialized the SIC module by changing its connection state from uninitialized to initialized. If the operation succeeds the 'eState' parameter of pfnCB is set to eCPMI_CERT_STATE_INITIALIZED and the 'stat' parameter will be CP_S_OK. Otherwise the 'eState' will be eCPMI_CERT_STATE_UNINITIALIZED and the 'stat' parameter will indicates the reason for failure.

Table 3-117 CPMIDbQueryApps arguments

argument meaning


nAppType bit-mask from tCPMI_APP_TYPE


pvOpaque User data to pass to pfnCB


CPMIAppCreateCertificate page 141

CPMIAppPushCertificate page 142

CPMIAppRevokeCertificate page 143

CPMIAppAttachLicense page 144

CPMIAppDetachLicense page 145

Applications

142

Prototypecpresult CPMIAppCreateCertificate (HCPMIAPP hApp,

const char *szPasswd,CPMICertificate_CB pfnCB, void *pvOpaque, cpmiopid *pOpId);

Arguments

Return Values


CPMIAppPushCertificate

CPMIAppPushCertificate pushes a certificate that has already been created. This function changes the connection state of the SIC module from initialized to communicating. If the operation succeeds the 'eState' parameter of pfnCB will be set to eCPMI_CERT_STATE_PUSHED and the 'stat' parameter will be CP_S_OK. Otherwise the 'eState' will be eCPMI_CERT_STATE_INITIALIZED and the 'stat' param will indicate the reason for failure.

Prototypecpresult CPMIAppPushCertificate (HCPMIAPP hApp,

CPMICertificate_CB pfnCB, void *pvOpaque, cpmiopid *pOpId);

Table 3-118 CPMIAppCreateCertificate arguments

argument meaning


szPasswd The password required by the Internal Certificate Authority.

pfnCB The function to be called once the certificate has been created. For more information, see “CPMICertificate_CB””.



Applications


Arguments

Return Values


CPMIAppRevokeCertificate

CPMIAppRevokeCertificate enables revoking an already created or pushed certificate. The purpose of this API is to change the module connection state from “initiated” to “unitialized”. If the operation succeeds the 'eState' parameter of pfnCB will be set to eCPMI_CERT_STATE_UNINITIALIZED and the 'stat' parameter will be CP_S_OK. Otherwise the 'eState' will be eCPMI_CERT_STATE_PUSHED and the 'stat' parameter will indicate the reason for failure.

Prototypecpresult CPMIAppRevokeCertificate (HCPMIAPP hApp,

CPMICertificate_CB pfnCB,void *pvOpaque, cpmiopid *pOpId);

Table 3-119 CPMIAppPushCertificate arguments

argument meaning


pfnCB The function to be called once the certificate has been pushed. For more information, see “CPMICertificate_CB””.



Applications

144

Arguments

Return Values


CPMIAppAttachLicense

CPMIAppAttachLicense associates a license object from the License Repository with a given application object.

Prototypecpresult CPMIAppAttachLicense (HCPMIAPP hApp,

HCPMIOBJ hObj,CPMILicense_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Table 3-120 CPMIAppRevokeCertificate arguments

argument meaning


pfnCB The function to be called once the certificate has been revoked. For more information, see “CPMICertificate_CB””.



Applications


Arguments

Return Values


CPMIAppDetachLicense

CPMIAPPDetachLicense detaches a license object from the License Repository from a given application object.

Prototypecpresult CPMIAppDetachLicense (HCPMIAPP hApp,

HCPMIOBJ hObj,CPMILicense_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Table 3-121 CPMIAppAttachLicense arguments

argument meaning


hObj Handle to license object.




Applications

146

Arguments

Return Values


Application Status RetrievalThe functions in this section retrieve the status of applications.

In This Section

CPMIDbGetAppsStatus

CPMIDbGetAppsStatus initiates a status request on a list of applications and returns the results.

Fetching with same network objects:

When fetching the status of one or more applications from the same network object, the pfnCB callback will be called once, with all the results, in the result parameter of pfnCB.

Fetching with different network objects:

When fetching the status of applications from different network objects, the pfnCB callback will be called once for each network object.

Table 3-122 CPMIAppDetachLicense arguments

argument meaning


hObj Handle to license object.




CPMIDbGetAppsStatus page 146

Classes in a Schema


Prototypecpresult CPMIDbGetAppsStatus (HCPMIDB hDb,

HCPMIAPP * rgApps, unsigned int nCount, CPMIQuery_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Arguments

Return Values


Classes in a SchemaThis section describes functions that manage the classes in a schema. For an example of Service Classes see “Details” on page 55.

In This Section

Table 3-123 CPMIDbGetAppsStatus arguments

argument meaning


rgApps An array of HCPMIAPPs.nCount The rgApps size.




Class Management page 148

Schema Class Iteration page 151

Classes in a Schema

148

Class ManagementThe functions described in this section enable you retrieve a handle to a class, to find out the class name and whether the class is derived from another class.

In This Section

CPMIClassGetTableName

CPMIClassGetTableName gets the class table name.

Prototypecpresult CPMIClassGetTableName (HCPMICLASS hClass, const char ** psz);

Arguments

Return Values


CPMIDbGetClassByName

CPMIDbGetClassByName returns a handle to the requested schema class.

Prototypecpresult CPMIDbGetClassByName (HCPMIDB hDb,

const char * szClassName, HCPMICLASS * phClass);

CPMIClassGetTableName page 148

CPMIDbGetClassByName page 148

CPMIClassGetName page 149

CPMIClassIsDerivedFrom page 149

CPMIClassGetDisplayString page 150

CPMIClassGetFieldByName page 150

Table 3-124 CPMIClassGetTableName arguments

argument meaning

hClass Handle to class.

psz Returned class name. *psz is set to NULL on failure. *psz should not be freed.

Classes in a Schema


Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CP_E_FAIL, CPMI_E_INVALID_CLASS.

CPMIClassGetName

CPMIClassGetName retrieves the name of the given class.

Prototypecpresult CPMIClassGetName (HCPMICLASS hClass, const char **psz);

Arguments

Return Values


CPMIClassIsDerivedFrom

CPMIClassIsDerivedFrom checks if the specified schema class is derived from another schema class.

Prototypecpresult CPMIClassIsDerivedFrom (HCPMICLASS hClass, const char *szClassName);

Table 3-125 CPMIDbGetClassByName arguments

argument meaning


szClassName The class name.

phClass The address of HCPMICLASS variable which receives the returned handle. *phClass is set to NULL upon failure. *phClass should be released when no longer needed.

Table 3-126 CPMIClassGetName arguments

argument meaning

hClass The class handle.

psz The address of a string variable which receives the class name. On failure, *psz is set to NULL.

Classes in a Schema

150

Arguments

Return Values

CP_S_OK, CP_S_FALSE, CP_E_INVALIDARG, CP_E_HANDLE.

CPMIClassGetDisplayString

CPMIClassGetDisplayString gets the class display string.

Prototypecpresult CPMIClassGetDisplayString (HCPMICLASS hClass, const char ** psz);

Arguments

Return Values


CPMIClassGetFieldByName

CPMIClassGetFieldByName gets the class display string.

Prototypecpresult CPMIClassGetFieldByName(HCPMICLASS hClass, const char * szFieldName,

Table 3-127 CPMIClassIsDerivedFrom arguments

argument meaning


szClassName The name of the base class which the given class checks against.

Note - If the given class does not have a display string, the returned string will be NULL.

Table 3-128 CPMIClassGetDisplayString arguments

argument meaning


psz The returned class display string. If there is none, *psz is set to NULL. *psz should not be freed.

Classes in a Schema


HCPMIFLD * phField);

Arguments

Return Values

CP_S_OK, CPMI_E_INVALID_FIELD, CP_E_INVALIDARG

Schema Class IterationThe following functions enable you to step through the classes in a schema.

In This Section

CPMIDbIterClasses

CPMIDbIterClasses gets an iteration handle to iterate over the schema classes on a given database.

Prototypecpresult CPMIDbIterClasses (HCPMIDB hDb, HCPMIITERCLASS * phIter);

Table 3-129 CPMIClassGetFieldByName arguments

argument meaning


szFieldName The requested field name.

phField The returned field. If there is none, *phField is set to NULL. *phField should be released with CPMIHandleRelease.

CPMIDbIterClasses page 151

CPMIIterClassGetNext page 152

CPMIIterClassGetCount page 152

CPMIIterClassIsDone page 153

CPMIIterClassIsEmpty page 153

CPMIIterClassRestart page 154

CPMIDbGetSchemaMajorVersion page 154

CPMIDbGetSchemaMinorVersion page 155

Classes in a Schema

152

Arguments

Return Values


CPMIIterClassGetNext

CPMIIterClassGetNext retrieves a handle to the next class in the schema, if this is the first call to the function, the first class handle is retrieved.

Prototypecpresult CPMIIterClassGetNext (HCPMIITERCLASS hIter, HCPMICLASS *phClass);

Arguments

Return Values


CPMIIterClassGetCount

CPMIIterClassGetCount retrieves the number of classes in the schema.

Prototypecpresult CPMIIterClassGetCount (HCPMIITERCLASS hIter, unsigned int * pCount);

Table 3-130 CPMIDbIterClasses arguments

argument meaning


phIter Address of HCPMIITERTBL to receive the iterator handle. *phIter is set to NULL upon failure. *phIter should be released when no longer needed.

Table 3-131 CPMIIterClassGetNext arguments

argument meaning

hIter The handle to the class iterator.

phClass The address of the HCPMICLASS variable to be set to the class handle. On failure, *phClass is set to NULL. *phClass should be released when no longer needed.

Classes in a Schema


Arguments

Return Values


CPMIIterClassIsDone

CPMIIterClassIsDone tests whether the iteration has been completed.

Prototypecpresult CPMIIterClassIsDone (HCPMIITERCLASS hIter);

Arguments

Return Values

CP_S_OK if the iteration is complete, CP_S_FALSE if the iteration is not complete,

or on failure CP_E_HANDLE.

CPMIIterClassIsEmpty

CPMIIterClassIsEmpty checks if the schema has no classes.

Prototypecpresult CPMIIterClassIsEmpty (HCPMIITERCLASS hIter);

Table 3-132 CPMIIterClassGetCount arguments

argument meaning


pCount The address of the unsigned int variable to be set to the number of classes. On failure, *pCount is set to ((unsigned int)-1).

Table 3-133 CPMIIterClassIsDone arguments

argument meaning


Classes in a Schema

154

Arguments

Return Values

CP_S_OK if the schema has no classes, CP_S_FALSE if the schema has one or more classes or on failure CP_E_HANDLE.

CPMIIterClassRestart

CPMIIterClassRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterClassRestart (HCPMIITERCLASS hIter);

Arguments

Return Values


CPMIDbGetSchemaMajorVersion

CPMIDbGetSchemaMajorVersion retrieves the schema major version.

Prototypecpresult CPMIDbGetSchemaMajorVersion (HCPMIDB hDb, unsigned int * pMajorVer);

Table 3-134 CPMIIterClassIsEmpty arguments

argument meaning


Table 3-135 CPMIIterClassRestart arguments

argument meaning


Classes in a Schema


Arguments

Return Values


CPMIDbGetSchemaMinorVersion

CPMIDbGetSchemaMinorVersion retrieves the schema minor version.

Prototypecpresult CPMIDbGetSchemaMinorVersion (HCPMIDB hDb, unsigned int * pMinorVer);

Arguments

Return Values


Table 3-136 CPMIDbGetSchemaMajorVersion arguments

argument meaning

hDb A handle to the database object.

pMajorVer The address of an unsigned int variable to receive the schema major version.

Table 3-137 CPMIDbGetSchemaMinorVersion arguments

argument meaning

hDb A handle to the database object.

pMinorVer The address of an unsigned int variable to receive the schema minor version.

Reference, Iteration and ID of Objects

156

Reference, Iteration and ID of ObjectsThis section describes functions that manage CPMI objects.

In This Section

Referencing ObjectsThe following functions enable you to reference and dereference objects in a table.

In This Section

CPMIRefCreateFromName

CPMIRefCreateFromName creates a reference to an object based on the name and table name of the object.

Prototypecpresult CPMIRefCreateFromName (const char* szTblName,

const char* szObjName, HCPMIREF *phRef);

Referencing Objects page 156

Object Iteration page 160

Object ID Utilities page 163

CPMIRefCreateFromName page 156

CPMIRefCreateFromObj page 157

CPMIRefGetReferencedObj page 157

CPMIRefGetObjectName page 158

CPMIRefGetTableName page 159

CPMIRefSetContext page 159



Arguments

Return Values


CPMIRefCreateFromObj

CPMIRefCreateFromObj creates a reference to an object based on the object’s handle.

Prototypecpresult CPMIRefCreateFromObj (HCPMI hObj, HCPMIREF *phRef);

Arguments

Return Values


CPMIRefGetReferencedObj

CPMIRefGetReferencedObj retrieves the referenced object.

Table 3-138 CPMIRefCreateFromName arguments

argument meaning

szTblName The table name.

szObjName The object name.

phRef The address of the HCPMIREF variable which receives the reference handle. On failure, *phRef is set to NULL. *phRef should be released when no longer needed.

Table 3-139 CPMIRefCreateFromObj arguments

argument meaning


phRef The address of the HCPMIREF variable which receives the reference handle. On failure, *phRef is set to NULL. *phRef should be released when no longer needed.


158

Prototypecpresult CPMIRefGetReferencedObj (HCPMIREF hRef,

HCPMIDB hDb, CPMIObj_CB pfnCB,void *pvOpaque, cpmiopid *pOpId);

Arguments

Return Values


CPMIRefGetObjectName

CPMIRefGetObjectName retrieves the referenced object’s name.

Prototypecpresult CPMIRefGetObjectName (HCPMIREF hRef, const char **psz);

Table 3-140 CPMIRefGetReferencedObj arguments

argument meaning

hRef The reference handle.

hDb The handle to the database containing the object.

pfnCB The function to be called when the object has been dereferenced. For more information, see “CPMIObj_CB””.





Arguments

Return Values


CPMIRefGetTableName

CPMIRefGetTableName retrieves the referenced object’s table name.

Prototypecpresult CPMIRefGetTableName (HCPMIREF hRef, const char **psz);

Arguments

Return Values


CPMIRefSetContext

CPMIRefSetContext sets a context definition for the reference. The Context will be used to reduce the object once the reference is de-referenced. For more information on Context see “CPMI Context Objects””.

Prototypecpresult CPMIRefSetContext (HCPMIREF hRef, HCPMICONTEXT hContext);

Table 3-141 CPMIRefGetObjectName arguments

argument meaning



Table 3-142 CPMIRefGetTableName arguments

argument meaning




160

Arguments

Return Values


Object IterationThe following functions enable you to step through the objects in the query result returned by CPMIResultIterObj (see page 112). For more information, see also “Querying Objects in Tables” on page 110.

In This Section

CPMIIterObjGetNext

CPMIIterObjGetNext retrieves a handle to the next object in the iteration, if this is the first call to the function, the first object handle is retrieved.

Prototypecpresult CPMIIterObjGetNext (HCPMIITEROBJ hIter, HCPMIOBJ *phObj);

Table 3-143 CPMIRefSetContext arguments

argument meaning



CPMIIterObjGetNext page 160

CPMIIterObjGetCount page 161

CPMIIterObjIsDone page 161

CPMIIterObjIsEmpty page 162

CPMIIterObjRestart page 162



Arguments

Return Values


CPMIIterObjGetCount

CPMIIterObjGetCount retrieves the number of objects in the query result.

Prototypecpresult CPMIIterObjGetCount (HCPMIITEROBJ hIter, unsigned int *pCount);

Arguments

Return Values


CPMIIterObjIsDone

CPMIIterObjIsDone tests if the iteration has been completed.

Prototypecpresult CPMIIterObjIsDone (CPMIITEROBJ hIter);

Table 3-144 CPMIIterObjGetNext arguments

argument meaning

hIter The handle to the object iterator, as returned by CPMIResultIterObj (see page 112).

phObj The address of the HCPMIOBJ variable which receives the object handle. On failure, *phObj is set to NULL. *phObj should be released.

Table 3-145 CPMIIterObjGetCount arguments

argument meaning

hIter The handle to the object iterator.

pCount The address of the unsigned int variable to be set to the number of objects. On failure, *pCount is set to ((unsigned int)-1).


162

Arguments

Return Values

CP_S_OK if there are no objects, CP_S_FALSE if the query is not empty or CP_E_HANDLE on failure.

CPMIIterObjIsEmpty

CPMIIterObjIsEmpty checks if there are any objects in the query result.

Prototypecpresult CPMIIterObjIsEmpty (HCPMIITEROBJ hIter);

Arguments

Return Values

CP_S_OK if there are no objects, CP_S_FALSE if the query is not empty or CP_E_HANDLE on failure.

CPMIIterObjRestart

CPMIIterObjRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterObjRestart (HCPMIITEROBJ hIter);

Table 3-146 CPMIIterObjIsDone arguments

argument meaning


Table 3-147 CPMIIterObjIsEmpty arguments

argument meaning




Arguments

Return Values


Object ID UtilitiesObjects have two ways of providing identification. The first one is the object’s name which is always unique on the object’s table. The second is a 128 bit number which is always guaranteed to be unique. This guaranteed number is the object’s unique id (UID).

This section lists utilities for handling UIDs.

In This Section

CPMIUidAreEqual

CPMIUidAreEqual compare two UIDs for exact matches.

Prototypecpresult CPMIUidAreEqual (const tCPMI_UID *pUid1, const tCPMI_UID *pUid2);

Table 3-148 CPMIIterObjReStart arguments

argument meaning


CPMIUidAreEqual page 163

CPMIUidToString page 164

CPMIUIDFromString page 164


164

Arguments

Return Values

CP_S_OK if the two identifiers are equal, CP_S_FALSE otherwise or CP_E_INVALIDARG on failure.

CPMIUidToString

CPMIUidToString convert a UID into an allocated string in the format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Prototypecpresult CPMIUidToString (const tCPMI_UID *pUid, char **psz);

Arguments

Return Values

CP_S_OK if successful or CP_E_INVALIDARG on failure.

CPMIUIDFromString

CPMIUIDFromString converts a string in the format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

into a UID.

Prototypecpresult CPMIUIDFromString (const char *szUid, tCPMI_UID *pUid);

Table 3-149 CPMIUidAreEqual arguments

argument meaning

pUid1 Pointer to the first UID.

pUid2 Pointer to the second UID.

Table 3-150 CPMIUidToString arguments

argument meaning

pUid The object ID.

psz Returned uid as string. On failure, *pszUid is set to NULL. *pszUid should be freed using CPMIFreeString.

Elements


Arguments

Return Values

CP_S_OK if successful or CP_E_INVALIDARG on failure.

ElementsThis section describes functions that manage elements in containers and ordered containers.

Element ManagementThis section describes the functions that manage elements in containers.

In This Section

CPMICntrAdd

CPMICntrAdd adds an element to the end of the specified container.

Table 3-151 CPMIUIDFromString arguments

argument meaning

szUid A string representing the object UID.

pUid The address of a tCPMI_UID variable which receives the converted UID. *pUid is set to a NULL UID on failure (a UID full of zeros).

Element Management page 165

Element Iteration page 168

Elements in Ordered Containers page 171

Ordered Element Iteration page 176

CPMICntrAdd page 165

CPMICntrGetCount page 166

CPMICntrRemove page 166

CPMICntrGetElementType page 167

Elements

166

Prototypecpresult CPMICntrAdd (HCPMICNTR hCnt, const tCPMI_FIELD_VALUE *pFv);

Arguments

Return Values


CPMICntrGetCount

CPMICntrGetCount retrieves the number of elements in a container.

Prototypecpresult CPMICntrGetCount (HCPMICNTR hCnt, unsigned int *pCount);

Arguments

Return Values


CPMICntrRemove

CPMICntrRemove removes the specified element from the container.

Prototypecpresult CPMICntrRemove (HCPMICNTR hCnt, tCPMI_FIELD_VALUE *pFv);

Table 3-152 CPMICntrAdd arguments

argument meaning


pFv The address of a tCPMI_FIELD_VALUE variable which contains the element to be added.

Table 3-153 CPMICntrGetCount arguments

argument meaning



Elements


Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CP_E_FAIL.

CPMICntrGetElementType

CPMICntrGetElementType retrieves the type of elements stored in the container.

Prototypecpresult CPMICntrGetElementType (HCPMICNTR hCnt, tCPMI_FIELD_TYPE *pType);

Arguments

Return Values


Table 3-154 CPMICntrRemove arguments

argument meaning


pFv The address of a tCPMI_FIELD_VALUE structure containing the element to be removed.

Table 3-155 CPMICntrGetElementType arguments

argument meaning


pType The address of tCPMI_FIELD_TYPE.

Elements

168

Element IterationThe following functions enable you to step through the elements in a container.

In This Section

CPMICntrIterElements

CPMICntrIterElements retrieves a handle to an element iterator object.

Prototypecpresult CPMICntrIterElements (HCPMICNTR hCnt, HCPMIITERCTNR *phIter);

Arguments

Return Values


CPMIIterCntrGetNext

CPMIIterCntrGetNext retrieves the next element in the container.

Prototypecpresult CPMIIterCntrGetNext (HCPMIITERCNTR hIter, tCPMI_FIELD_VALUE *pValue);

CPMICntrIterElements page 168

CPMIIterCntrGetNext page 168

CPMIIterCntrGetCount page 169

CPMIIterCntrIsDone page 169

CPMIIterCntrIsEmpty page 170

CPMIIterCntrRestart page 170

Table 3-156 CPMICntrIterElements arguments

argument meaning


phIter The address of the HCPMIITERCNTR variable to be set to the element iterator handle. On failure, *phIter is set to NULL. *phIter should be released when done.

Elements


Arguments

Return Values


CPMIIterCntrGetCount

CPMIIterCntrGetCount retrieves the number of elements in the container iteration.

Prototypecpresult CPMIIterCntrGetCount (HCPMIITERCNTR hIter, unsigned int *pCount);

Arguments

Return Values


CPMIIterCntrIsDone

CPMIIterCntrIsDone tests whether the iteration has been completed.

Prototypecpresult CPMIIterCntrIsDone (HCPMIITERCNTR hIter);

Table 3-157 CPMIIterCntrGetNext arguments

argument meaning

hIter The handle to the container iterator.

pValue Address of the tCPMI_FIELD_VALUE variable to be set to the element. On failure, pValue->fvt is set to eCPMI_FVT_UNDEFINED.

Table 3-158 CPMIIterCntrGetCount arguments

argument meaning



Elements

170

Arguments

Return Values

CP_S_OK if the iteration is complete. CP_S_FALSE if the iteration is not complete.


CPMIIterCntrIsEmpty

CPMIIterCntrIsEmpty checks if the container iterator is empty.

Prototypecpresult CPMIIterCntrIsEmpty (HCPMIITERCNTR hIter);

Arguments

Return Values

CP_S_OK if the container is empty. CP_S_FALSE if container has one or more elements.


CPMIIterCntrRestart

CPMIIterCntrRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterCntrRestart (HCPMIITERCNTR hIter);

Table 3-159 CPMIIterCntrIsDone arguments

argument meaning


Table 3-160 CPMIIterCntrIsEmpty arguments

argument meaning


Elements


Arguments

Return Values

CP_S_OK if successful.


Elements in Ordered ContainersThis section describes the functions that manage elements in ordered containers.

In This Section

CPMIOrderCntrAdd

CPMIOrderCntrAdd adds an element to the end of an ordered container.

Prototypecpresult CPMIOrderCntrAdd (HCPMIORDERCNTR hCnt,

const tCPMI_FIELD_VALUE *pElem);

Table 3-161 CPMIIterCntrRestart arguments

argument meaning


CPMIOrderCntrAdd page 171

CPMIOrderCntrAddAt page 172

CPMIOrderCntrGetAt page 172

CPMIOrderCntrGetCount page 173

CPMIOrderCntrIndexOf page 173

CPMIOrderCntrGetElementType page 174

CPMIOrderCntrRemove page 175

CPMIOrderCntrRemoveAt page 175

Elements

172

Arguments

Return Values


CPMIOrderCntrAddAt

CPMIOrderCntrAddAt adds an element at a specific location in the ordered container.

Prototypecpresult CPMIOrderCntrAddAt (HCPMIORDERCNTR hCnt,

unsigned int nIndex,const tCPMI_FIELD_VALUE *pElem);

Arguments

Return Values


CPMIOrderCntrGetAt

CPMIOrderCntrGetAt retrieves the element at the specified location in the container.

Prototypecpresult CPMIOrderCntrGetAt (HCPMIORDERCNTR hCnt,

Table 3-162 CPMIOrderCntrAdd arguments

argument meaning

hCnt The ordered container handle.

pElem The address of a tCPMI_FIELD_VALUE structure containing the element to be added.

Table 3-163 CPMIOrderCntrAddAt arguments

argument meaning


nIndex The index of the location where the element is to be added (zero based).

pElem The address of a tCPMI_FIELD_VALUE structure containing the element to be added.

Elements


unsigned int nIndex, tCPMI_FIELD_VALUE *pVal);

Arguments

Return Values


CPMIOrderCntrGetCount

CPMIOrderCntrGetCount retrieves the number of elements in the ordered container.

Prototypecpresult CPMIOrderCntrGetCount (HCPMIORDERCNTR hCnt, unsigned int *pCount);

Arguments

Return Values


CPMIOrderCntrIndexOf

CPMIOrderCntrIndexOf retrieves the index of the location of the element in the ordered container.

Table 3-164 CPMIOrderCntrGetAt arguments

argument meaning


nIndex The index of the location where the element is to be retreived (zero based).

pVal The address of a tCPMI_FIELD_VALUE structure that receives the returned element.

Table 3-165 CPMIOrderCntrGetCount arguments

argument meaning


pCount The address of a unsigned int variable to be set to the number of elements in the container. On failure, *pCount is set to ((unsigned int)-1).

Elements

174

Prototypecpresult CPMIOrderCntrIndexOf (HCPMIORDERCNTR hCnt,

const tCPMI_FIELD_VALUE *pElem, unsigned int *pIndex);

Arguments

Return Values


CPMIOrderCntrGetElementType

CPMIOrderCntrGetElementType gets the type of the elements stored in the ordered container.

Prototypecpresult CPMIOrderCntrGetElementType (HCPMIORDERCNTR hOrdCnt,

tCPMI_FIELD_TYPE * pType);

Arguments

Return Values


Table 3-166 CPMIOrderCntrIndexOf arguments

argument meaning


pElem The address of a tCPMI_FIELD_VALUE structure containing the element.

pIndex The address of an unsigned int variable to be set to the position of the element. On failure, *pIndex is set to ((unsigned int)-1).

Table 3-167 CPMIOrderCntrGetElementType arguments

argument meaning

hOrdCnt The handle to the ordered container

ptype The address of a tCPMI_FIELD_TYPE enum to receive the elements type.

Elements


CPMIOrderCntrRemove

CPMIOrderCntrRemove removes an element from the container.

Prototypecpresult CPMIOrderCntrRemove (HCPMIORDERCNTR hCnt,

const tCPMI_FIELD_VALUE *pElem);

Arguments

Return Values


CPMIOrderCntrRemoveAt

CPMIOrderCntrRemoveAt removes the element from a specified location in the container.

Prototypecpresult CPMIOrderCntrRemoveAt (HCPMIORDERCNTR hCnt, unsigned int nIndex);

Arguments

Return Values


Table 3-168 CPMIOrderCntrRemove arguments

argument meaning


pElem The address of a tCPMI_FIELD_VALUE structure containing the element to be removed.

Table 3-169 CPMIOrderCntrRemoveAt arguments

argument meaning


nIndex The index to the element’s location (zero based).

Elements

176

Ordered Element IterationThe following functions enable you to step through the elements in an ordered container.

In This Section

CPMIOrderCntrIterElements

CPMIOrderCntrIterElements retrieves a handle to an ordered container iterator.

Prototypecpresult CPMIOrderCntrIterElements (HCPMIORDERCNTR hCnt,

HCPMIITERCNTR *phIter);

Arguments

Return Values


CPMIIterOrdCntrGetNext

CPMIIterOrdCntrGetNext retrieves the next element in the ordered container.

Prototypecpresult CPMIIterOrdCntrGetNext (HCPMIITERCNTR hIter,

CPMIOrderCntrIterElements page 176

CPMIIterOrdCntrGetNext page 176

CPMIIterOrdCntrGetCount page 177

CPMIIterOrdCntrIsDone page 177

CPMIIterOrdCntrIsEmpty page 178

CPMIIterOrdCntrRestart page 178

Table 3-170 CPMIOrderCntrIterElements arguments

argument meaning


phIter The address of the HCPMIITERCNTR variable to be set to the iterator handle. On failure, *phIter is set to NULL.*phIter should be released when no longer needed.

Elements


tCPMI_FIELD_VALUE *pValue);

Arguments

Return Values


CPMIIterOrdCntrGetCount

CPMIIterOrdCntrGetCount retrieves the number of elements in the ordered container iterator.

Prototypecpresult CPMIIterOrdCntrGetCount (HCPMIITERCNTR hIter, unsigned int *pCount);

Arguments

Return Values


CPMIIterOrdCntrIsDone

CPMIIterOrdCntrIsDone tests whether the iteration has been completed.

Prototypecpresult CPMIIterOrdCntrIsDone (HCPMIITERCNTR hIter);

Table 3-171 CPMIIterOrdCntrGetNext arguments

argument meaning


pValue Address of the tCPMI_FIELD_VALUE variable to be set to the element. On failure, pValue->fvt is set to eCPMI_FVT_UNDEFINED.

Table 3-172 CPMIIterOrdCntrGetCount arguments

argument meaning



Elements

178

Arguments

Return Values

CP_S_OK if the iteration is complete. CP_S_FALSE if the iteration is not complete.


CPMIIterOrdCntrIsEmpty

CPMIIterOrdCntrIsEmpty checks if the ordered container iterator is empty.

Prototypecpresult CPMIIterOrdCntrIsEmpty (HCPMIITERCNTR hIter);

Arguments

Return Values

CP_S_OK if the container is empty. CP_S_FALSE if container has one or more elements.


CPMIIterOrdCntrRestart

CPMIIterOrdCntrRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Prototypecpresult CPMIIterOrdCntrRestart (HCPMIITERCNTR hIter);

Table 3-173CPMIIterOrdCntrIsDone arguments

argument meaning


Table 3-174 CPMIIterOrdCntrIsEmpty arguments

argument meaning


Fields


Arguments

Return Values


FieldsThis section describes functions that manage the fields of a CPMI object.

Managing Field PropertiesThe functions below enable you to modify and return information about a specified field’s properties.

In This Section“CPMIFldGetName” on page 185

Table 3-175 CPMIIterOrdCntrRestart arguments

argument meaning


Managing Field Properties page 179

Field Iteration page 189

CPMIObjSetFieldValue page 180

CPMIObjSetFieldValueByName page 180

CPMIFldGetDisplayString page 181

CPMIObjGetField page 181

CPMIObjGetFieldAsString page 182

CPMIObjGetFieldValue page 183

CPMIObjGetFieldValueByName page 184

CPMIFldGetName page 185

CPMIFldGetSize page 185

CPMIFldGetType page 185

CPMIFldGetValidValues page 186

CPMIFldIsMultiple page 187

CPMIFldIsOrdered page 187

Fields

180

CPMIObjSetFieldValue

CPMIObjSetFieldValue sets a value to a given field. If the field type on the schema does not match pNewVal->fvt the function fails.

Prototypecpresult CPMIObjSetFieldValue (HCPMIOBJ hObj,

HCPMIFLD hFld, const tCPMI_FIELD_VALUE * pNewVal)

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CP_E_ACCESSDENIED if the database is not open in read/write mode, CP_E_FAIL on failure or CPMI_E_INVALID_FIELD when the field is incompatible with the schema.

CPMIObjSetFieldValueByName

CPMIObjSetFieldValueByName sets a value to field identifid by it's field name. If the field type on the schema does not match pNewVal->fvt the function fails.

Prototypecpresult CPMIObjSetFieldValueByName (HCPMIOBJ hObj,

const char * szFldName, const tCPMI_FIELD_VALUE * pNewVal);

Table 3-176 CPMIObjSetFieldValue arguments

argument meaning


hFld The handle to the field.

pNewVal The address of a tCPMI_FIELD_VALUE structure containing the value to set. The value must match the field’s type as in the schema. For more information see “Fields” on page 17.

Fields


Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CP_E_ACCESSDENIED if the database is not open in read/write mode, CP_E_FAIL on failure or CPMI_E_INVALID_FIELD when the field is incompatible with the schema.

CPMIFldGetDisplayString

CPMIFldGetDisplayString returns a string representing the field. If no string is present NULL is returned.

Prototypecpresult CPMIFldGetDisplayString (HCPMIFLD hFld, const char ** psz);

Arguments

Return Values


CPMIObjGetField

CPMIObjGetField gets a handle to a field from an object.

Table 3-177 CPMIObjSetFieldValueByName arguments

argument meaning


szFldName The name of the field to change.

pVal The address of a tCPMI_FIELD_VALUE structure containing the value to set. The value must match the field’s type as in the schema. For more information see “Fields” on page 17.

Table 3-178 CPMIFldGetDisplayString arguments

argument meaning

hFld The field handle.

psz The address of a string variable which receives the field’s string representation. On failure, *psz is set to NULL. *psz should not be freed.

Fields

182

Prototypecpresult CPMIObjGetField (HCPMIOBJ hObj,

const char * szFldName, HCPMIFLD * phFld);

Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG, CP_E_HANDLE, CPMI_E_INVALID_FIELD.

CPMIObjGetFieldAsString

CPMIObjGetFieldAsString gets the field value formatted as a string.

Prototypecpresult CPMIObjGetFieldAsString (HCPMIOBJ hObj,

const char * szFldName, char ** psz);

Table 3-179 CPMIObjGetField arguments

argument meaning


szFldName The requested field name.

phFld The address of HCPMIFLD variable which receives the field handle. *phFld is set to NULL upon failure. *phFld should be released when no longer needed.

Fields


Arguments

Return Values


CPMIObjGetFieldValue

CPMIObjGetFieldValue gets a field value from an object. Upon successful function call, the field type can be determined from the pVal->fvt. pVal->objFv and pVal->refFv can be NULL even when the function is return successfully. Upon failure, prVal->fvt is set to eCPMI_FVT_UNDEFINED and all other members are invalid.

Prototypecpresult CPMIObjGetFieldValue (HCPMIOBJ hObj,

HCPMIFLD hFld, tCPMI_FIELD_VALUE * pVal);

Table 3-180 CPMIObjGetFieldAsString arguments

argument meaning


szFldName The requested field name.

psz The address of a string variable which receives the field value formatted as a string. *psz should be freed (using CPMIFreeString) when no longer needed. On failure, *psz is set to NULL.

Fields

184

Arguments

Return Values


CPMIObjGetFieldValueByName

CPMIObjGetFieldValueByName gets a field value from an object. Upon successful function call, the field type can be determined from the pVal->fvt. pVal->objFv and pVal->refFv can be NULL even when the function is return successfully. Upon failure, prVal->fvt is set to eCPMI_FVT_UNDEFINED and all other members are invalid.

PrototypeCPMIObjGetFieldValueByName (HCPMIOBJ hObj,

const char * szFldName, tCPMI_FIELD_VALUE * pVal);

Arguments

Return Values


Table 3-181 CPMIObjGetFieldValue arguments

argument meaning



pVal The address of a tCPMI_FIELD_VALUE structure which receives the field value. In cases where the return value is a handle then the handle should be released with CPMIHandleRelease see “CPMIHandleRelease” on page 62.

Table 3-182 CPMIObjGetFieldValueByName arguments

argument meaning


szFldName The field name.

pVal The address of a tCPMI_FIELD_VALUE structure which receives the field value.

Fields


CPMIFldGetName

CPMIFldGetName retrieves the name of the given field.

Prototypecpresult CPMIFldGetName (HCPMIFLD hFld, const char **psz);

Arguments

Return Values


CPMIFldGetSize

CPMIFldGetSize retrieves the specified field’s size in bytes.

Prototypecpresult CPMIFldGetSize (HCPMIFLD hFld, unsigned int *pSize);

Arguments

Return Values


CPMIFldGetType

CPMIFldGetType retrieves the field’s type.

Table 3-183 CPMIFldGetName arguments

argument meaning


psz The address of a string variable which receives the field name. On failure, *psz is set to NULL. *psz should not be freed.

Table 3-184 CPMIFldGetSize arguments

argument meaning


pSize The address of a unsigned int variable which receives the field size, in bytes. On failure, *pSize is set to ((unsigned int)-1).

Fields

186

Prototypecpresult CPMIFldGetType (HCPMIFLD hFld, tCPMI_FIELD_TYPE *pType);

Arguments

Return Values


CPMIFldGetValidValues

CPMIFldGetValidValues retrieves the valid values of a given field as it appears on the schema.

Prototypecpresult CPMIFldGetValidValues (HCPMIFLD hFld, const char **psz);

Table 3-185 CPMIFldGetType arguments

argument meaning


pType The address of the tCPMI_FIELD_TYPE variable to be set to the field type. Field type may be one of the following:

field type

eCPMI_FT_UNDEFINED

Undefined (error).

eCPMI_FT_STR Field is of string type.

eCPMI_FT_NUM Field is of numeric type.

eCPMI_FT_U_NUM Field is of unsigned int type.

eCPMI_FT_NUM64 Field is of 64 bit int type.

eCPMI_FT_U_NUM64 Field is of unsigned 64 bit int type.

eCPMI_FT_BOOL Field is of boolean type.

eCPMI_FT_OWNED_OBJ

Field type is “owned object”. See “Fields””.

Fields


Arguments

Return Values


CPMIFldIsMultiple

CPMIFldIsMultiple checks if the field type is container.

Prototypecpresult CPMIFldIsMultiple (HCPMIFLD hFld);

Arguments

Return Values

CP_S_OK if the field type is container. CP_S_FALSE if the field is not of type container and CP_E_HANDLE on failure.

CPMIFldIsOrdered

CPMIFldIsOrdered checks if the field type is ordered container.

Prototypecpresult CPMIFldIsOrdered (HCPMIFLD hFld);

Table 3-186 CPMIFldGetValidValues arguments

argument meaning


psz Returned valid values. On failure, *psz is set to NULL. *psz should not be freed.

Table 3-187 CPMIFldIsMultiple arguments

argument meaning


Fields

188

Arguments

Return Values

CP_S_OK if the field type is ordered container. CP_S_FALSE if the field is not of type ordered container and CP_E_HANDLE on failure.

CPMIFldGetDefaultValue

CPMIFldGetDefaultValue gets the default field value..

Prototypecpresult CPMIFldGetDefaultValue(HCPMIFLD hFld, const char ** psz);

Arguments

Return Values


Table 3-188 CPMIFldIsOrdered arguments

argument meaning


Table 3-189 CPMIFldGetDefaultValue arguments

argument meaning


psz Returned default value. *psz set to NULL on failure

Fields


Field IterationThe following functions enable you to iterate over the class fields.

In This Section

CPMIClassIterFields

CPMIClassIterFields retrieves a handle to a field iterator object.

Prototypecpresult CPMIClassIterFields (HCPMICLASS hClass, HCPMIITERFLD *phIter);

Arguments

Return Values


CPMIClassIterFields page 189

CPMIIterFldGetNext page 190

CPMIIterFldGetCount page 190

CPMIIterFldIsDone page 191

CPMIIterFldIsEmpty page 191

CPMIIterFldRestart page 191

CPGetErrorMessage page 192

CP_SUCCEEDED page 193

CP_FAILED page 193

CPMIDbGetExtendedErrorMessage page 194

Table 3-190 CPMIClassIterFields arguments

argument meaning


phIter The address of the HCPMIITERFLD variable to be set to the iterator handle. On failure, *phIter is set to NULL. *phIter should be released when no longer needed.

Fields

190

CPMIIterFldGetNext

CPMIIterFldGetNext retrieves a handle to the next field in the class, if this is the first call to the function, the first field handle is retrieved.

Prototypecpresult CPMIIterFldGetNext (HCPMIITERFLD hIter, HCPMIFLD *phFld);

Arguments

Return Values


CPMIIterFldGetCount

CPMIIterFldGetCount retrieves the number of fields in the class.

Prototypecpresult CPMIIterFldGetCount (HCPMIITERFLD hIter, unsigned int *pCount);

Arguments

Return Values


Table 3-191 CPMIIterFldGetNext arguments

argument meaning

hIter The handle to the field iterator.

phFld The address of the HCPMIFLD variable to be set to the field handle.On failure, *phFld is set to NULL. *phFld should be released when no longer needed.

Table 3-192 CPMIIterFldGetCount arguments

argument meaning


pCount The address of the unsigned int variable to be set to the number of fields. On failure, *pCount is set to ((unsigned int)-1).

Fields


CPMIIterFldIsDone

CPMIIterFldIsDone tests whether the iteration has been completed.

Prototypecpresult CPMIIterFldIsDone (HCPMIITERFLD hIter);

Arguments

Return Values


CPMIIterFldIsEmpty

CPMIIterFldIsEmpty checks if the iteration object is empty.

Prototypecpresult CPMIIterFldIsEmpty (HCPMIITERFLD hIter);

Arguments

Return Values

CP_S_OK if the iteration has no fields. CP_S_FALSE if the iteration has one or more fields.


CPMIIterFldRestart

CPMIIterFldRestart starts the iteration over from the beginning. This function can be called anytime during the iteration.

Table 3-193 CPMIIterFldIsDone arguments

argument meaning


Table 3-194 CPMIIterFldIsEmpty arguments

argument meaning


Errors

192

Prototypecpresult CPMIIterFldRestart (HCPMIITERFLD hIter);

Arguments

Return Values


ErrorsThis section describes functions that manage CPMI errors.

In This Section

CPGetErrorMessage

CPGetErrorMessage gets a string description for a given cpresult.

Prototype

const char* CPGetErrorMessage (cpresult nErr);

Table 3-195 CPMIIterFldRestart arguments

argument meaning


CPGetErrorMessage page 192

CP_SUCCEEDED page 193

CP_FAILED page 193

CPMIDbGetExtendedErrorMessage page 194

Errors


Arguments

Return Values

The message associated with given cpresult, or NULL.

CP_SUCCEEDED

CP_SUCCEEDED is a generic test for success on any cpresult value. Typically CP_SUCCEEDED is used in an “if statement” as follows:

PrototypeCP_SUCCEEDED (cpresult_code);

Arguments

Return Values

True indicates that given cpresult is successful, otherwise false indicates failure.

CP_FAILED

CP_FAILED is a generic test for failure on any cpresult value. Typically CP_FAILED is used in an “if statement” as follows:

Table 3-196 CPGetErrorMessage arguments

argument meaning

nErr Error code

cpresult res = CPMIDbRegisterEvent (...);if ( CP_SUCCEEDED (res) ){ . . .}

Table 3-197 CP_SUCCEEDED arguments

argument meaning

cpresult_code cpresult value

cpresult res = CPMIDbRegisterEvent (...);if ( CP_FAILED (res) ){ . . .}

Errors

194

PrototypeCP_FAILED (cpresult_code);

Arguments

Return Values

True indicates that given cpresult is a failure, otherwise false indicates a success.

CPMIDbGetExtendedErrorMessage

CPMIDbGetExtendedErrorMessage finds out if an error string for this operation exists, and if so, returns it. In some cases, a descriptive string value is stored and associated with a cpmiopid. This function returns the string that is currently associated with cpmiopid. These strings are valid only when the cpmiopid is valid which is usually in the context of a callback.

Prototypecpresult CPMIDbGetExtendedErrorMessage (HCPMIDB hDb,

cpmiopid opId, char ** psz);

Arguments

Return Values


Table 3-198 CP_FAILED arguments

argument meaning

cpresult_code cpresult value

Table 3-199 CPMIDbGetExtendedErrorMessage arguments

argument meaning


opId A valid operation id, or 0 (zero) for last error message that is not associated to any cpmiopid.

psz address of string variable to receive the returned string. *psz is set to NULL upon failure. Free string using CPMIFreeString.

Event Registration and Notification


Event Registration and NotificationThis section describes functions that manage CPMI event notification.

Register and UnregisterThe functions described below enable you to register and unregister a callback function for notifications on events that happen on the database.

In This Section

CPMIDbRegisterEvent

CPMIDbRegisterEvent enables you to register a callback function for notifications on events that happen on the database.

Prototypecpresult CPMIDbRegisterEvent (HCPMIDB hDb,

HCPMITBL hTbl, HCPMIOBJ hObj, unsigned int nEvents, unsigned int nFlags, CPMINotify_CB pfnCB, void * pvOpaque, cpmiopid * pOpId);

Register and Unregister page 195

Getting Notification Information page 198

CPMIDbRegisterEvent page 195

CPMIDbUnregisterEvent page 197


196

Arguments

Table 3-200 CPMIDbRegisterEvent arguments

argument meaning

hDb A handle to the database.

hTbl A handle to the table where notifications are requested. Pass NULL to receive notifications from all tables.

hObj If hObj is not NULL then only notifications that relate to hObj are processed. If hObj is NULL then notifications from all objects in hTbl are processed.

nEvents Bitmask of values from tCPMI_NOTIFY_EVENT specifying desired events:

eCPMI_NOTIFY_DELETE Register for notification on object deletion.

eCPMI_NOTIFY_UPDATE Register for notification on object update.

eCPMI_NOTIFY_RENAME Register for notification on object rename.

eCPMI_NOTIFY_CREATE Register for notification on object creation.

eCPMI_NOTIFY_STATUS_CHANGE Register for notification on application status changes.

eCPMI_NOTIFY_INSTALL_POLICY

Register for notification on policy installation.

eCPMI_NOTIFY_UNINSTALL_POLICY

Register for notification on removal of a policy.



Return Values


CPMIDbUnregisterEvent

CPMIDbUnregisterEvent cancel a previous call to CPMIDbRegisterevent. If successful, the callback function that was registered in the call to CPMIDbRegisterEvent will be called with an error code of CPMI_E_OPERATION_MEM_CLEANUP so resources can be released.

Prototype

cpresult CPMIDbUnregisterEvent (HCPMIDB hDb, cpmiopid opId);

nFlags Bitmask of values from tCPMI_NOTIFY_FLAGS specifying additional flags.

eCPMI_FLAG_SEND_OBJECT Object that triggered the notification is sent with the notification message. By default the object is NOT sent in order to save network bandwidth.

eCPMI_FLAG_GET_SELF_CHANGES

Allows an application to receive a notification that the application itself triggered. By default notifications are sent only to other registered applications, not the one that triggered them.

pfnCB User function to be called when the operation is done. To indicate a successful registration pfnCB is called with a CP_S_OK status code and hMgs is NULL. If registration fails then pfnCB is called with an error code and hMgs is NULL.



Table 3-200 CPMIDbRegisterEvent arguments(continued)

argument meaning


198

Arguments

Return Values


Getting Notification InformationThis section describes functions that retrieve information from a notification message.

In This Section

CPMINotifyGetEvent

CPMINotifyGetEvent retrieves the type of event that triggered the notification.

Prototypecpresult CPMINotifyGetEvent (HCPMINOTIFYMSG hMsg,

tCPMI_NOTIFY_EVENT * pEvent);

Table 3-201 CPMIDbUnRegisterEvent arguments

argument meaning


opId The cpmiopid that was returned in the call to CPMIDbRegisterEvent.

CPMINotifyGetEvent page 198

CPMINotifyGetModifierHost page 199

CPMINotifyGetUid page 199

CPMINotifyGetModifierUser page 200

CPMINotifyGetObj page 200

CPMINotifyGetObjName page 201

CPMINotifyGetTblName page 201

CPMINotifyGetTime page 202

CPMINotifyGetOldName page 202



Arguments

Return Values


CPMINotifyGetModifierHost

CPMINotifyGetModifierHost retrieves the name of the host from which the event was triggered.

Prototypecpresult CPMINotifyGetModifierHost (HCPMINOTIFYMSG hMsg, const char **psz);

Arguments

Return Values


CPMINotifyGetUid

CPMINotifyGetUid retrieves the uid of the object that triggered the notification.

Prototypecpresult CPMINotifyGetUid (HCPMINOTIFYMSG hMsg, const char **psz);

Table 3-202 CPMINotifyGetEvent arguments

argument meaning

hMsg The notification message handle.

pEvent The address of tCPMI_NOTIFY_EVENT variable which receives the notification event type.

Table 3-203 CPMINotifyGetModifierHost arguments

argument meaning


psz The address of a string variable which receives the host name. On failure, *psz is set to NULL. *psz should not be freed


200

Arguments

Return Values


CPMINotifyGetModifierUser

CPMINotifyGetModifierUser retrieves the name of the administrator whose modification triggered the event.

Prototypecpresult CPMINotifyGetModifierUser (HCPMINOTIFYMSG hMsg, const char **psz);

Arguments

Return Values


CPMINotifyGetObj

CPMINotifyGetObj retrieves the handle of the object that triggered the event.

Table 3-204 CPMINotifyGetUid arguments

argument meaning


psz The address of a string variable which receives the UID string. On failure, *psz is set to NULL. *psz should not be freed.

Table 3-205 CPMINotifyGetModifierUser arguments

argument meaning


psz The address of a string variable which receives the administrator name. On failure, *psz is set to NULL. *psz should not be freed.

Note - The returned object handle will be valid only if the flag eCPMI_FLAG_GET_SELF_CHANGES was used in the registration stage or the notification is about status changes i.e. notification type is eCPMI_NOTIFY_STATUS_CHANGE.



Prototypecpresult CPMINotifyGetObj (HCPMINOTIFYMSG hMsg, HCPMIOBJ *phObj);

Arguments

Return Values


CPMINotifyGetObjName

CPMINotifyGetObjName retrieves the name of the object that triggered the event.

Prototypecpresult CPMINotifyGetObjName (HCPMINOTIFYMSG hMsg, const char **psz);

Arguments

Return Values


CPMINotifyGetTblName

CPMINotifyGetTblName retrieves the name of the table containing the object that triggered the event.

Prototypecpresult CPMINotifyGetTblName (HCPMINOTIFYMSG hMsg, const char **psz);

Table 3-206 CPMINotifyGetObj arguments

argument meaning


phObj The address of the HCPMIOBJ which receives the object handle. On failure, *phObj is set to NULL. *phObj should be released when no longer needed.

Table 3-207 CPMINotifyGetObjName arguments

argument meaning


psz The address of string variable which receives the object name. On failure, *psz is set to NULL.*psz should not be freed.


202

Arguments

Return Values


CPMINotifyGetTime

CPMINotifyGetTime retrieves the time the event was triggered.

Prototypecpresult CPMINotifyGetTime (HCPMINOTIFYMSG hMsg, time_t *pTime);

Arguments

Return Values


CPMINotifyGetOldName

CPMINotifyGetOldName returns the old name of the object after a rename notification event.

Prototypecpresult CPMINotifyGetOldName (HCPMINOTIFYMSG hMsg, const char ** psz);

Table 3-208 CPMINotifyGetTblName arguments

argument meaning


psz The address of a string variable which receives the table name. On failure, *psz is set to NULL.*psz should not be freed.

Table 3-209 CPMINotifyGetTime arguments

argument meaning


pTime The address of a time_t variable which receives the time of event. On failure, *pTime is set to ((time_t)0).



Arguments

Return Values

CP_S_OK, CP_E_INVALIDARG.

Table 3-210 CPMINotifyGetOldName arguments

argument meaning


psz The address of a the constant char* variable to receive the old name.

Event Handlers

204

Event HandlersThis section describes the prototype of callback functions that are used in CPMI.

The function prototypes are defined in CPMIClientDataTypes.h.

In This Section

Operation IDThe operation ID (cpmiopid) is a unique number that each asynchronous api returns to identify itself. If several operations are done with the same callback given to all of them, this is the way to match a result to an operation.

CPMIBind_CBCPMIBind_CB is the prototype of the bind callback. The bind callback is called when a connection to the database has been established and authenticated — see also “CPMISessionBind” on page 69 and “CPMISessionBindUser” on page 68.

PrototypeeOpsecHandlerRC CPMIBind_CB (OpsecSession *pSession,

cpresult stat,void *pvOpaque);

Operation ID page 204

CPMIBind_CB page 204

CPMICertificate_CB page 205

CPMIObj_CB page 206

CPMINotify_CB page 207

CPMIDb_CB page 208

CPMIQuery_CB page 209

CPMILicense_CB page 210

CPMICertificate_CB


Arguments

Return Values

OPSEC_SESSION_OK if the session can continue.

OPSEC_SESSION_END if the session is to be closed.

OPSEC_SESSION_ERR if the session is to be closed due to an error.

CPMICertificate_CBCPMICertificate_CB is the prototype of the certificate operations callback.

PrototypeeOpsecHandlerRC CPMICertificate_CB (HCPMIDB hDb, HCPMIAPP hApp, tCPMI_CERT_STATE eState, cpresult stat, cpmiopid opid, void *pvOpaque);

Table 3-211 CPMIBind_CB arguments

argument meaning

pSession A pointer to an OpsecSession structure, as returned by CPMISessionNew.

stat The status of the operation. CP_S_OK if successful. The reason for failure otherwise.

pvOpaque User-supplied data.

CPMIObj_CB

206

Arguments

Return Values




CPMIObj_CBCPMIObj_CB is the prototype of an object related operation callback

PrototypeeOpsecHandlerRC CPMIObj_CB (HCPMIDB hDb,

HCPMIOBJ hObj, cpresult stat, cpmiopid opid, void *pvOpaque);

Table 3-212 CPMICertificate_CB arguments

argument meaning


hApp The application object handle.

eState The certificate state. One of:

event meaning

eCPMI_CERT_STATE_UNINITIALIZED

The certificate was not created.

eCPMI_CERT_STATE_INITIALIZED The certificate has been created but not pushed.

eCPMI_CERT_STATE_PUSHED The certificate has been pushed successfully.


opid The operation ID. (for an explanation of cpmiopid see page 204).


CPMINotify_CB


Arguments

Return Values




CPMINotify_CBCPMINotify_CB is the prototype of the notifications callback.

PrototypeeOpsecHandlerRC CPMINotify_CB (HCPMIDB hDb,

HCPMINOTIFYMSG hMsg, cpresult stat,cpmiopid opid, void *pvOpaque);

Table 3-213 CPMIObj_CB arguments

argument meaning






CPMIDb_CB

208

Arguments

Return Values




CPMIDb_CBCPMIDb_CB is the prototype of the database related operations callback.

PrototypeeOpsecHandlerRC CPMIDb_CB (HCPMIDB hDb,

cpresult stat, cpmiopid opid, void *pvOpaque);

Table 3-214 CPMINotify_CB arguments

argument meaning


hMsg A handle to the notification message containing information about the event. To retrieve this information, see “Getting Notification Information” on page 198.




CPMIQuery_CB


Arguments

Return Values




CPMIQuery_CBCPMIQuery_CB is the prototype of the query operations callback.

PrototypeeOpsecHandlerRC CPMIQuery_CB (HCPMIDB hDb,

HCPMIRSLT result, cpresult stat,cpmiopid opid, void *pvOpaque);

Table 3-215 DB_CB arguments

argument meaning





CPMILicense_CB

210

Arguments

Return Values




CPMILicense_CBCPMILicense_CB is the prototype of the license operations callback.

PrototypeeOpsecHandlerRC CPMILicence_CB (HCPMIDB hDb,

HCPMIAPP hApp, tCPMI_LIC_STATE eState, cpresult stat, cpmiopid opid, void *pvOpaque);

Table 3-216 CPMIQuery_CB arguments

argument meaning


result A handle to a result object. The result object is a container of objects that are the result of the query operation.




CPMILicense_CB


Arguments

Return Values




Table 3-217 CPMILicense_CB arguments

argument meaning


hApp A handle to the application object where the operation was done.

eState One value from the tCPMI_LIC_STATE:

eCPMI_LIC_STATE_UNINITIALIZED

License is not initialized. Indicates an error.

eCPMI_LIC_STATE_ATTACHED License has been successfully attached.

eCPMI_LIC_STATE_DETACHED License has been successfully detached.




Error Codes

212

Error CodesTable 3-218 and Table 3-219 lists CPMI error codes and their meaning. Unless otherwise stated all error codes are defined in CPMIErrors.h.

In This Section

Error Codes defined in cperrors.h page 212

General Error Codes page 213

Object Related Error Codes page 213

Database Related Error Codes page 214

Query Related Error Codes page 214

Policy or Status Related Error Codes page 214

Table Related Error Codes page 214

Schema Related Error Codes page 215

Management Related Error Codes page 215

OPSEC Related Error Codes page 215

License Related Error Codes page 215

Table 3-218 Error Codes defined in cperrors.h

code meaning

CP_S_OK The Operation Finished Successfully.

CP_S_FALSE The Operation Finished Successfully. Used to indicate false code in a true/false operation.

CP_E_ABORT Operation aborted.

CP_E_ACCESSDENIED Access denied.

CP_E_DLLNOTFOUND DLL for class not found.

CP_E_FAIL Unspecified error.

CP_E_HANDLE Bad handle.

CP_E_INVALIDARG One or more invalid arguments.

CP_E_ITER_NOMORE Unable to iterate because associated data is missing.

CP_E_NOTIMPL Requested operation is not implemented.

CP_E_OUTOFMEMORY Out of memory.

Error Codes


CP_E_PENDING Data required to complete operation is not yet available.

CP_E_POINTER Invalid pointer.

CP_E_READFAULT A disk error occurred during a read operation.

CP_E_THREAD_CREATE Cannot create another thread.

CP_E_TIMEOUT Timeout period expired.

CP_E_UNEXP_NET_ERR Unexpected network error.

CP_E_UNEXPECTED Catastrophic failure.

CP_E_WRITEFAULT A disk error occurred during a write operation.

Table 3-219 General Error Codes

code meaning

CPMI_E_VERSION_MISMATCH client/server versions mismatch

CPMI_E_SEND_AUDIT_LOG failed to send audit log

Table 3-220 Object Related Error Codes

code meaning

CPMI_E_OBJ_NOT_FOUND object not found

CPMI_E_OBJ_CREATE object creation failed

CPMI_E_OBJ_UPDATE object update failed

CPMI_E_OBJ_DELETE object deletion failed

CPMI_E_OBJ_REGISTERED object is already registered

CPMI_E_OBJ_VALIDATION object validation failed

CPMI_E_OBJ_LOCK object lock failed

CPMI_E_OBJ_LOCKED object is already locked

CPMI_E_OBJ_EXIST object already exists

CPMI_E_OBJ_UPDATE_REFERENCES object references update failed

CPMI_E_OBJ_DELETE_REFERENCES object references deletion failed

CPMI_E_OBJ_DELETEABLE object can not be deleted

Table 3-218 Error Codes defined in cperrors.h

code meaning

Error Codes

214

Table 3-221 Database Related Error Codes

code meaning

CPMI_E_DB_LOCK database lock error

CPMI_E_DB_BACKUP database backup error

CPMI_E_DB_RESTORE database restore error

CPMI_E_DB_NOT_FOUND database not found

CPMI_E_DB_ALREADY_OPEN database already open

CPMI_E_DB_NOT_OPEN database in not open

Table 3-222 Query Related Error Codes

code meaning

CPMI_E_QUERY general query error

CPMI_E_QUERY_NOT_FOUND query not found

CPMI_E_QUERY_SYNTAX bad query syntax

Table 3-223 Policy or Status Related Error Codes

code meaning

CPMI_E_POLICY_NOT_FOUND policy not found

CPMI_E_RULE_NOT_FOUND rule not found

CPMI_E_AGENT_DISCONNECT agent disconnected

CPMI_E_BAD_REPLY bad status report

CPMI_E_NOT_INSTALLED product not installed

CPMI_E_UNTRUSTED untrusted host

Table 3-224 Table Related Error Codes

code meaning

CPMI_E_TBL_N0T_FOUND table not found

CPMI_E_TBL_LOCK table lock failed

Error Codes


Table 3-225 Schema Related Error Codes

code meaning

CPMI_E_INVALID_CLASS invalid schema class

CPMI_E_INVALID_FIELD invalid schema field

CPMI_E_NO_VALUE empty field value

Table 3-226 Management Related Error Codes

code meaning

CPMI_E_MGMT_NOT_ACTIVE SmartCenter Server not active

Table 3-227 OPSEC Related Error Codes

code meaning

CPMI_E_OPSEC_SESSION general OPSEC session error

CPMI_E_OPERATION_MEM_CLEANUP session about to end

CPMI_E_SESSION_NOT_CONNECTED session not connected

CPMI_E_SESSION_NOT_BOUNDED session not bounded

Table 3-228 License Related Error Codes

code meaning

CPMI_E_LICENSE_NOT_FOUND license not found

CPMI_E_LICENSE_EXIST license already exists

Error Codes

216

217

Appendix ACPMIClientDataTypes.h Data Type

The following are the data types required by CPMI clients only.

/** certificate possible states */enum tagCPMI_LIC_STATE { /** uninitialized */ eCPMI_LIC_STATE_UNINITIALIZED = 1,

/** attached successfully */ eCPMI_LIC_STATE_ATTACHED,

/** detached successfully */ eCPMI_LIC_STATE_DETATCHED};/** typedef for tagCPMI_LIC_STATE */typedef enum tagCPMI_LIC_STATE tCPMI_LIC_STATE;

TABLE 0-1 tCPMI_CERT_STATE enumeration

enumerator description

tagCPMI_CERT_STATE or tCPMI_CERT_STATE

certificate possible states

eCPMI_CERT_STATE_UNINITIALIZED = 1 uninitialized

eCPMI_CERT_STATE_INITIALIZED created but not pushed

eCPMI_CERT_STATE_PUSHED pushed succesfully

218

/* ////////////////////////////////////////////////////////////////////////// * * * callback definitions * * ////////////////////////////////////////////////////////////////////////// */typedef eOpsecHandlerRC (*pfnCPMIBind_CB) (OpsecSession * pSession, cpresult stat, void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMIObj_CB) (HCPMIDB hDb , HCPMIOBJ hObj , cpresult stat , cpmiopid opid , void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMIDb_CB) (HCPMIDB hDb , cpresult stat , cpmiopid opid , void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMIQuery_CB) (HCPMIDB hDb , HCPMIRSLT result , cpresult stat , cpmiopid opid , void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMINotify_CB) (HCPMIDB hDb , HCPMINOTIFYMSG hMsg , cpresult stat , cpmiopid opid , void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMICertificate_CB) (HCPMIDB hDb , HCPMIAPP hApp , tCPMI_CERT_STATE eState , cpresult stat , cpmiopid opid , void * pvOpaque);

Chapter A CPMIClientDataTypes.h Data Type 219

typedef eOpsecHandlerRC (*pfnCPMILicense_CB) (HCPMIDB hDb , HCPMIAPP hApp , tCPMI_LIC_STATE eState , cpresult stat , cpmiopid opid , void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMIDbCertificate_CB) (HCPMIDB hDb , const char * szSicName , char cert_bin_buf[64*1024] , int nBufLen , cpresult stat , cpmiopid opid , void * pvOpaque);

typedef eOpsecHandlerRC (*pfnCPMIDbUser_CB) (HCPMIDB hDb , const char * szSicName , tCPMI_CERT_STATE eState , int iRefNum , const char * szAuthCode , const char * szAuthValidity , const char * szCertificate, int nBufLen, cpresult stat , cpmiopid opid , void * pvOpaque);

/**The user function will be called separately for every application object from the application array.@paramh Db: handle to db where installation occurred.@param refApp: reference to the application for which there is a report.@param state: the installation state of hApp.@params stateResult = result for state.@paramszMessage = extended string message@isLast = is last notification for this state (CP_S_OK or CP_S_FALSE).@paramopid = operation id as was returned from CPMIAppsInstallPolicy/CPMIAppsUninstallPolicy.@parampvOpq = user data as was passed to CPMIAppsInstallPolicy/CPMIAppsUninstallPolicy */typedef eOpsecHandlerRC (*pfnCPMIPolicyInstall_CB) (HCPMIDB hDb, HCPMIREF refApp, tCPMI_POLICY_INSTALL_STATE state, cpresult stateResult, const char* szMessage, cpresult isLast,

220

cpmiopid opid, void * pvQpq);

/** simple callback */typedef pfnCPMIBind_CB CPMIBind_CB;

/** object callback */typedef pfnCPMIObj_CB CPMIObj_CB;

/** db callback */typedef pfnCPMIDb_CB CPMIDb_CB;

/** query callback */typedef pfnCPMIQuery_CB CPMIQuery_CB;

/** notification callback */typedef pfnCPMINotify_CB CPMINotify_CB;

/** certificate operation callback */typedef pfnCPMICertificate_CB CPMICertificate_CB;

/** license operation callback */typedef pfnCPMILicense_CB CPMILicense_CB;

/** db certificate operation callback */typedef pfnCPMIDbCertificate_CB CPMIDbCertificate_CB;

/** getreferrals operation callback */typedef pfnCPMIQuery_CB CPMIGetReferrals_CB;

/** init and get_status user certificate callback */typedef pfnCPMIDbUser_CB CPMIDbUser_CB;

/** install operation callback */typedef pfnCPMIPolicyInstall_CB CPMIPolicyInstall_CB;

/*@}*/#endif /*CPMICLIENTDATATYPES_H_EBAF8F61912D11d3B7690090272CCB30*//* ////////////////////// EOF CPMIClientDataTypes.h ////////////////////// */

135

THIRD PARTY TRADEMARKS AND COPYRIGHTS

Entrust is a registered trademark of Entrust Technologies, Inc. in the United States and other countries. Entrust’s logos and Entrust product and service names are also trademarks of Entrust Technologies, Inc. Entrust Technologies Limited is a wholly owned subsidiary of Entrust Technologies, Inc. FireWall-1 and SecuRemote incorporate certificate management technology from Entrust.

Verisign is a trademark of Verisign Inc.

The following statements refer to those portions of the software copyrighted by University of Michigan. Portions of the software copyright © 1992-1996 Regents of the University of Michigan. All rights reserved. Redistribution and use in source and binary forms are permitted provided that this notice is preserved and that due credit is given to the University of Michigan at Ann Arbor. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. This software is provided “as is” without express or implied warranty. Copyright © Sax Software (terminal emulation only).

The following statements refer to those portions of the software copyrighted by Carnegie Mellon University.

Copyright 1997 by Carnegie Mellon University. All Rights Reserved.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of CMU not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The following statements refer to those portions of the software copyrighted by The Open Group.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The following statements refer to those portions of the software copyrighted by The OpenSSL Project. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The following statements refer to those portions of the software copyrighted by Eric Young. THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Copyright © 1998 The Open Group.

136

The following statements refer to those portions of the software copyrighted by Jean-loup Gailly and Mark Adler Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler. This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

The following statements refer to those portions of the software copyrighted by the Gnu Public License. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

The following statements refer to those portions of the software copyrighted by Thai Open Source Software Center Ltd and Clark Cooper Copyright (c) 2001, 2002 Expat maintainers. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.GDChart is free for use in your applications and for chart generation. YOU MAY NOT re-distribute or represent the code as your own. Any re-distributions of the code MUST reference the author, and include any and all original documentation. Copyright. Bruce Verderaime. 1998, 1999, 2000, 2001. Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health. Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002 by Boutell.Com, Inc. Portions relating to GD2 format copyright 1999, 2000, 2001, 2002 Philip Warner. Portions relating to PNG copyright 1999, 2000, 2001, 2002 Greg Roelofs. Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002 John Ellson ([email protected]). Portions relating to gdft.c copyright 2001, 2002 John Ellson ([email protected]). Portions relating to JPEG and to color quantization copyright 2000, 2001, 2002, Doug Becker and copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, Thomas G. Lane. This software is based in part on the work of the Independent JPEG Group. See the file README-JPEG.TXT for more information. Portions relating to WBMP copyright 2000, 2001, 2002 Maurice Szmurlo and Johan Van den Brande. Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation. This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. "Derived works" includes all programs that utilize the library. Credit must be given in user-accessible documentation. This software is provided "AS IS." The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation. Although their code does not appear in gd 2.0.4, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

The curl license

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1996 - 2004, Daniel Stenberg, <[email protected]>.All rights reserved.

Permission to use, copy, modify, and distribute this software for any purpose

with or without fee is hereby granted, provided that the above copyright

notice and this permission notice appear in all copies.

Chapter 137

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

The PHP License, version 3.0

Copyright (c) 1999 - 2004 The PHP Group. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, is permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name "PHP" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

4. Products derived from this software may not be called "PHP", nor may "PHP" appear in their name, without prior written permission from [email protected]. You may indicate that your software works in conjunction with PHP by saying "Foo for PHP" instead of calling it "PHP Foo" or "phpfoo"

5. The PHP Group may publish revised and/or new versions of the license from time to time. Each version will be given a distinguishing version number. Once covered code has been published under a particular version of the license, you may always continue to use it under the terms of that version. You may also choose to use such covered code under the terms of any subsequent version of the license published by the PHP Group. No one other than the PHP Group has the right to modify the terms applicable to covered code created under this License.

6. Redistributions of any form whatsoever must retain the following acknowledgment:

"This product includes PHP, freely available from <http://www.php.net/>".

THIS SOFTWARE IS PROVIDED BY THE PHP DEVELOPMENT TEAM ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE PHP DEVELOPMENT TEAM OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the PHP Group. The PHP Group can be contacted via Email at [email protected].

For more information on the PHP Group and the PHP project, please see <http://www.php.net>. This product includes the Zend Engine, freely available at <http://www.zend.com>.

This product includes software written by Tim Hudson ([email protected]).

Copyright (c) 2003, Itai Tzur <[email protected]>

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistribution of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Neither the name of Itai Tzur nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission.

138

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright © 2003, 2004 NextHop Technologies, Inc. All rights reserved.

Confidential Copyright Notice

Except as stated herein, none of the material provided as a part of this document may be copied, reproduced, distrib-uted, republished, downloaded, displayed, posted or transmitted in any form or by any means, including, but not lim-ited to, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of NextHop Technologies, Inc. Permission is granted to display, copy, distribute and download the materials in this doc-ument for personal, non-commercial use only, provided you do not modify the materials and that you retain all copy-right and other proprietary notices contained in the materials unless otherwise stated. No material contained in this document may be "mirrored" on any server without written permission of NextHop. Any unauthorized use of any material contained in this document may violate copyright laws, trademark laws, the laws of privacy and publicity, and communications regulations and statutes. Permission terminates automatically if any of these terms or condi-tions are breached. Upon termination, any downloaded and printed materials must be immediately destroyed.

Trademark Notice

The trademarks, service marks, and logos (the "Trademarks") used and displayed in this document are registered and unregistered Trademarks of NextHop in the US and/or other countries. The names of actual companies and products mentioned herein may be Trademarks of their respective owners. Nothing in this document should be construed as granting, by implication, estoppel, or otherwise, any license or right to use any Trademark displayed in the document. The owners aggressively enforce their intellectual property rights to the fullest extent of the law. The Trademarks may not be used in any way, including in advertising or publicity pertaining to distribution of, or access to, materials in

this document, including use, without prior, written permission. Use of Trademarks as a "hot" link to any website is prohibited unless establishment of such a link is approved in advance in writing. Any questions concerning the use of these Trademarks should be referred to NextHop at U.S. +1 734 222 1600.

U.S. Government Restricted Rights

The material in document is provided with "RESTRICTED RIGHTS." Software and accompanying documentation are provided to the U.S. government ("Government") in a transaction subject to the Federal Acquisition Regulations with Restricted Rights. The Government's rights to use, modify, reproduce, release, perform, display or disclose are

restricted by paragraph (b)(3) of the Rights in Noncommercial Computer Software and Noncommercial Computer Soft-ware Documentation clause at DFAR 252.227-7014 (Jun 1995), and the other restrictions and terms in paragraph (g)(3)(i) of Rights in Data-General clause at FAR 52.227-14, Alternative III (Jun 87) and paragraph (c)(2) of the Commer-cial

Computer Software-Restricted Rights clause at FAR 52.227-19 (Jun 1987).

Use of the material in this document by the Government constitutes acknowledgment of NextHop's proprietary rights in them, or that of the original creator. The Contractor/Licensor is NextHop located at 1911 Landings Drive, Mountain View, California 94043. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in applicable laws and regulations.

Chapter 139

Disclaimer Warranty Disclaimer Warranty Disclaimer Warranty Disclaimer Warranty

THE MATERIAL IN THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTIES OF ANY KIND EITHER EXPRESS OR IMPLIED. TO THE FULLEST EXTENT POSSIBLE PURSUANT TO THE APPLICABLE LAW, NEXTHOP DISCLAIMS ALL WARRANTIES,

EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON INFRINGEMENT OR OTHER VIOLATION OF RIGHTS. NEITHER NEXTHOP NOR ANY OTHER PROVIDER OR DEVELOPER OF MATERIAL CONTAINED IN THIS DOCUMENT WARRANTS OR MAKES ANY REPRESEN-TATIONS REGARDING THE USE, VALIDITY, ACCURACY, OR RELIABILITY OF, OR THE RESULTS OF THE USE OF, OR OTHERWISE RESPECTING, THE MATERIAL IN THIS DOCUMENT.

Limitation of Liability

UNDER NO CIRCUMSTANCES SHALL NEXTHOP BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA OR PROFIT, ARISING OUT OF THE USE, OR THE INABILITY TO USE, THE MATERIAL IN THIS DOCUMENT, EVEN IF NEXTHOP OR A NEXTHOP AUTHORIZED REPRESENTATIVE HAS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IF YOUR USE OF MATERIAL FROM THIS DOCUMENT RESULTS IN THE NEED FOR SERVICING, REPAIR OR CORRECTION OF EQUIPMENT OR DATA, YOU ASSUME ANY COSTS THEREOF. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT FULLY APPLY TO YOU.

Copyright © ComponentOne, LLC 1991-2002. All Rights Reserved.

BIND: ISC Bind (Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC"))

Copyright 1997-2001, Theo de Raadt: the OpenBSD 2.9 Release

PCRE LICENCE

PCRE is a library of functions to support regular expressions whose syntax and semantics are as close as possible to those of the Perl 5 language. Release 5 of PCRE is distributed under the terms of the "BSD" licence, as specified below. The documentation for PCRE, supplied in the "doc" directory, is distributed under the same terms as the software itself.

Written by: Philip Hazel <[email protected]>

University of Cambridge Computing Service, Cambridge, England. Phone:

+44 1223 334714.

Copyright (c) 1997-2004 University of Cambridge All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of the University of Cambridge nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

June 2006 227

Index

Aadmin tables 24administrator user name and

password 36application objects 32applications tables 25asymmetric authentication 38asynchronous functions 49attribute value query

integer 46real 46string 45

attribute value types 45auditing 47

Ccaching 45class

definition of 25classes definition 25containers 22context

functions 134context object 40CP_FAILED (cpresult_code) 193CP_SUCCEEDED

(cpresult_code) 193CPGetErrorMessage 192CPMI API Overview 32CPMI Context Objects 40CPMI general utilities 64CPMIAppAttachLicense 144CPMIAppCreateCertificate 141CPMIAppDetachLicense 145CPMIAppGetObject 140CPMIAppPushCertificate 142CPMIAppRevokeCertificate 143CPMIClassGetDisplayString 150CPMIClassGetName 149

CPMIClassGetTableName 148CPMIClassIsDerivedFrom 149CPMIClassIterFields 189CPMIClientAPIs 60CPMICntrAdd 165CPMICntrGetCount 166CPMICntrGetElementType 167CPMICntrRemove 166CPMIContextCreate 134, 135CPMIDbAcquireLockByRef 119CPMIDbClose 81CPMIDbCreateCertificate 70CPMIDbCreateObject 115CPMIDbDeleteObjByRef 117CPMIDbGetAppsStatus 146CPMIDbGetClassByName 148CPMIDbGetExtendedErrorMessag

e 194CPMIDbGetName 83CPMIDbGetOpenMode 82CPMIDbGetSchemaMajorVersion

154CPMIDbGetSchemaMinorVersion

155CPMIDbGetSession 83CPMIDbGetTable 99CPMIDbIterClasses 151CPMIDbIterTables 102CPMIDbOpen 81CPMIDbQueryApps 140CPMIDBQueryTables 87CPMIDBQueryTablesByContext 9

4CPMIDbRegisterEvent 195CPMIDbReleaseLockByRef 120CPMIDbRevokeCertificate 71CPMIDbUnregisterEvent 197CPMIFldGetDisplayString 181CPMIFldGetName 185CPMIFldGetSize 185CPMIFldGetType 185CPMIFldGetValidValues 186CPMIFldIsMultiple 187

CPMIFldIsOrdered 187CPMIFreeString 61CPMIGetMajorReleaseVer 64CPMIGUIDFromString 164CPMIHandleAddRef 61CPMIHandleRelease 62CPMIIterClassGetCount 152CPMIIterClassGetNext 152CPMIIterClassIsDone 153CPMIIterClassIsEmpty 153CPMIIterClassRestart 154CPMIIterCntrGetCount 169CPMIIterCntrGetNext 168CPMIIterCntrIsDone 169CPMIIterCntrIsEmpty 170CPMIIterCntrRestart 170CPMIIterDbGetCount 96CPMIIterDbGetNext 96CPMIIterDbIsDone 97CPMIIterDbIsEmpty 97CPMIIterDbRestart 98CPMIIterFldGetCount 190CPMIIterFldGetNext 190CPMIIterFldIsDone 191CPMIIterFldIsEmpty 191CPMIIterFldRestart 191CPMIIterObjGetCount 161CPMIIterObjGetNext 160CPMIIterObjIsDone 161CPMIIterObjIsEmpty 162CPMIIterObjRestart 162CPMIIterOrdCntrGetCount 177CPMIIterOrdCntrGetNext 176CPMIIterOrdCntrIsDone 177CPMIIterOrdCntrIsEmpty 178CPMIIterOrdCntrRestart 178CPMIIterTblGetCount 103CPMIIterTblGetNext 103CPMIIterTblIsDone 104CPMIIterTblIsEmpty 104CPMIIterTblStart 105CPMILicense_CB 210CPMINotifyGetEvent 198

228

CPMINotifyGetModifierHost 199CPMINotifyGetModifierUser 200CPMINotifyGetObj 200, 201CPMINotifyGetOldName 202CPMINotifyGetTblName 201CPMINotifyGetTime 202CPMINotifyGetUid 199CPMIObjAcquireLock 118CPMIObjClone 131CPMIObjDelete 116CPMIObjGetAppHandle 139CPMIObjGetClassName 127CPMIObjGetDb 125CPMIObjGetField 181CPMIObjGetFieldAsString 182CPMIObjGetFieldValue 183CPMIObjGetFieldValueByName 1

84CPMIObjGetLastModifier 128CPMIObjGetLastModifyHost 128CPMIObjGetLastModifyTime 129CPMIObjGetName 125CPMIObjGetReferrals 129CPMIObjGetTbl 126CPMIObjGetUID 126CPMIObjIsDeletable 116CPMIObjIsOfClass 127CPMIObjIsOwned 130CPMIObjIsReduced 109CPMIObjReleaseLock 120CPMIObjSetFieldValue 180CPMIObjSetFieldValueByName 1

80CPMIObjSetName 124CPMIObjUpdate 117CPMIObjValidate 121CPMIOrderCntrAdd 171CPMIOrderCntrAddAt 172CPMIOrderCntrGetAt 172CPMIOrderCntrGetCount 173CPMIOrderCntrGetElementType 1

74CPMIOrderCntrIndexOf 173CPMIOrderCntrRemove 175CPMIOrderCntrRemoveAt 175CPMIRefCreateFromName 156CPMIRefCreateFromObj 157CPMIRefGetObjectName 158CPMIRefGetReferencedObj 157

CPMIRefGetTableName 159CPMIRefSetContext 159CPMIReleaseFieldValue 63CPMIResultIterObj 112CPMISessionBind 69CPMISessionBindUser 68CPMISessionEnd 68CPMISessionGetServerHAMode 7

6CPMISessionGetServerMajorVersi

on 75CPMISessionGetServerMinorVersi

on 75CPMISessionGetServerRunType 7

7CPMISessionGetServerType 77CPMISessionGetTimeout 74CPMISessionIterDb 95CPMISessionNew 67CPMISessionSetCachePath 72CPMISessionSetTimeout 74CPMISessionUseCache 73CPMITblDeleteObj 108CPMITblGetDB 100CPMITblGetDisplayString 101CPMITblGetName 100CPMITblGetObj 107CPMITblGetObjByContext 107CPMITblIsWriteable 101CPMITblQueryObjects 111CPMITblQueryObjectsByContext

111CPMIUidAreEqual 163CPMIUidToString 164create an object 28

Ddefinition of CPMI 14delete an object 28development flow 27

Eencryption tables 25error codes 212

error handling 34establishing a CPMI session 35event handling 49

asynchronous functions 49events

register and unregister 195external database tables 25

Ffield definitions attribute

defvalue 18multiple 18name 18ordered 18type 18validvalues 18

field iteration handle 28fields

definition 17linked object 18member object 17owned object 17type definition 18

fields data type mapping 51function return values 34

GGeneral Object Management 114

Iiteration 48iteration functions

CPMIIterYYYGetCount 48CPMIIterYYYGetNext 48CPMIIterYYYIsDone 48CPMIIterYYYIsEmpty 48CPMIIterYYYRestart 48CPMIUUUIterVVV 48

Llocking objects 44

229

MM/O

definition 22memory management 35miscellaneous tables 25modify an existing object 28

Nnaming conventions 33notification 43

Oobject

creation 28deletion 28functions that manage 106handle to class 28modification 28

object class inheritance 20object classification 21object definition 15object definition files

definition 15object definitions attribute

validvalues 20object definitions field attribute

defvalue 20field name 19field type 19multiple 20

object level attributebaseobj 20owned 20validfunc 20

object status monitoring 47object type definition module 23object uniqueness 42operation ID 204OPSEC tables 25OPSEC_ASYM_SSLCA 38OPSEC_SSLCA 39

Ppartial object retrieval 39password 36policies tables 24possible field types 17programming Model 30properties tables 24pType definitions 186

Qqueries 45

Ssample field definition 18schema

definition 15schema definitions objects

excerpt 22schema overview 54sections of scheme.html 54session version identification 38single-quotation marks 45symmetric authentication 39

Ttable

defintion of 25third-party applications

enabled to use 30

Uuser name 36

CPMI (Check Point Management Inter- face) API...

Documents

Transcript of CPMI (Check Point Management Inter- face) API...