ctaGetServiceVersionEx

Retrieves the version of the specified Natural Access service from a specified server.

Prototype

DWORD ctaGetServiceVersionEx ( CTAHD ctahd, CTA_SERVICE_NAME *svcname, CTA_REV_INFO *pinfo, unsigned size)

Argument	Description
ctahd	Context handle that specifies the server on which commands are executed. ctahd can be a void context handle.
svcname	Pointer to a structure specifying a service. The CTA_SERVICE_NAME structure is: typedef struct { char svcname; / Service name (eg. "ADI", "SWI" ...)/ char svcmgrname; /* Service manager providing service */ } CTA_SERVICE_NAME;
pinfo	Pointer to a buffer to receive the CTA_REV_INFO structure, as shown: typedef struct { DWORD size; /* Size of the returned structure / DWORD majorrev; / Major revision of service / DWORD minorrev; / Minor revision of service / char builddate [12]; / Build date, "Mmm dd yyyy\0" / DWORD compatlevel; / Compatibility level of API */ } CTA_REV_INFO; See the Details section for field descriptions.
size	Size of the CTA_REV_INFO data structure.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	pinfo is NULL.
CTAERR_BAD_SIZE	size is smaller than the size of DWORD.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_NOT_FOUND	Specified service or service manager set is not initialized.
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.
CTAERR_SVR_COMM	Server communication error.

Details

ctaGetServiceVersionEx retrieves the version of an initialized service. ctahd can be a void context handle. A void context handle refers only to the server on which the commands are executed and not to any real context object. Each server has a unique void context handle. If the void context handle is equal to NULL_CTAHD, it refers to the default server.

ctaGetServiceVersionEx performs programmatic checking of the installed and initialized service version. Use the information returned in the CTA_REV_INFO structure to check the minimum required service revision and compatibility level.

The CTA_REV_INFO structure contains the following fields:

Field	Description
size	Number of bytes written at the address pointed to by pinfo.
majorrev	Major revision number of the initialized service. This value changes when a service release contains major enhancements such as new APIs.
minorrev	Minor revision number of the initialized service. This value changes when a service release contains minor enhancements, bug fixes, or both.
builddate	A NULL-terminated string indicating the build date of the service, in mm dd yyyy format.
compatlevel	Compatibility level of the specified service. The compatibility level changes when the release includes enhancements that require an application to be re-compiled because the changes are not backward compatible, for example, API signature change.

Example

int CheckRequiredVersion( CTA_SERVICE_NAME *svcname, DWORD compatlevel )
{
    CTA_REV_INFO info;

    CTAHD void_ctahd;
    /* Server name descriptor  */
    char server_desc[] = "host.nmss.com:2244";
    /* Create a void context handle */
    ctaCreateContext(NULL_CTAQUEUEHD, 0, server_desc, &void_ctahd);

    ctaGetServiceVersionEx( void_ctahd, svcname, &info, sizeof info );
    if ( info.compatlevel < compatlevel )
    {
        return FAILURE;
    }
    printf( "(%s) service version (%d.%d) installed.\n", svcname->svcname,
            info.majorver, info.minorver );
    return SUCCESS;
}