ctaGetServiceVersion

Retrieves the version of the specified Natural Access service.

Prototype

DWORD ctaGetServiceVersion ( CTA_SERVICE_NAME *svcname, CTA_REV_INFO *pinfo, unsigned size)

Argument

Description

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_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

ctaGetServiceVersion 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 requiring an application to be recompiled because the changes are not backward compatible, for example, API signature change.


See also

ctaGetServiceVersionEx

Example

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

    ctaGetServiceVersion( 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;
}