ncGlobalGetOption()

Info Value
Header mvnc.h
Library libmvnc.so
Version 2.0
See also ncGlobalOption_t, ncGlobalSetOption()

Overview

This function gets the value of a global option. The available options and possible values can be found in the ncGlobalOption_t enumeration.

Prototype

ncStatus_t ncGlobalGetOption(int option, void* data, unsigned int* dataLength);

Parameters

Name Type Description
option int A value from the ncGlobalOption_t enumeration that specifies which option’s value will be retrieved.
data void* A pointer to a buffer where the value of the option will be copied. The size and type of data this points to will depend on the option that is specified. See ncGlobalOption_t for option data types.
dataLength unsigned int* A pointer to an unsigned int which contains the size, in bytes, of the buffer allocated by the caller for the data parameter.

Upon normal return (status code NC_OK), dataLength will be set to the number of bytes copied to the data buffer. In the event that the data buffer was an insufficient size to hold the option value, the return status code will be NC_INVALID_DATA_LENGTH and dataLength will be set to the size required to hold the option value.

Return

An appropriate value from the ncStatus_t enumeration.

If the data buffer was an insufficient size to hold the option value, the return status code will be NC_INVALID_DATA_LENGTH and dataLength will be set to the size required to hold the option value.

Notes

  • If you don’t know what value to use for dataLength, you can call this function once with a dataLength of 0 to have dataLength be set to the correct value and then allocate a correctly sized buffer and call this function again. See the example below.

Example

Get an option value when you know the correct data length:

#include <mvnc.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) 
{
    ncStatus_t retCode;
    int logLevel;
    unsigned int dataLength;

    /* Get the logging level option value */
    dataLength = sizeof(logLevel);
    retCode = ncGlobalGetOption(NC_RW_LOG_LEVEL, &logLevel, &dataLength);

    /* retCode should be NC_OK unless there was a problem */
    if(retCode != NC_OK)
    {
        printf("Error: %d\n", retCode);
        exit(-1);
    }

    /* Use the log level as needed */
    printf("LOGGING LEVEL IS %d\n", logLevel);
    
    return 0;
}

Get an option value when you don’t know the correct data length:

#include <mvnc.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) 
{
    ncStatus_t retCode;
    unsigned int* apiVersion;
    unsigned int dataLength;

    /* Call once to get the correct dataLength */
    apiVersion = NULL;
    dataLength = 0;
    retCode = ncGlobalGetOption(NC_RO_API_VERSION, apiVersion, &dataLength);

    /* retCode should be NC_INVALID_DATA_LENGTH unless there was another problem */
    if(retCode != NC_INVALID_DATA_LENGTH)
    {
        printf("Error: %d\n", retCode);
        exit(-1);
    }

    /* Now the value of dataLength is correctly set (in this case for an array of 4 unsigned ints) */
    /* Allocate the array buffer */
    apiVersion = (unsigned int*)malloc(dataLength);

    /* Call the function again to get the API version option value */
    retCode = ncGlobalGetOption(NC_RO_API_VERSION, apiVersion, &dataLength);
    
    /* Now retCode should be NC_OK unless there was another problem */
    if(retCode != NC_OK)
    {
        printf("Error: %d\n", retCode);
        exit(-1);
    }

    /* Use the API version as needed */
    printf("API VERSION - Major: %d, Minor: %d, Hotfix: %d, Release: %d\n", apiVersion[0], apiVersion[1], apiVersion[2], apiVersion[3]);

    /* When you are done, free it and set the pointer to NULL */
    free(apiVersion);
    apiVersion = NULL;
    
    return 0;
}