ARGetMultipleImages

Important

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

Description

Retrieves information from the specified server about the images whose names are specified in the nameList parameter. This function performs the same action as ARGetImage, but it is more efficient than retrieving information about multiple images one by one. Information is returned in lists for each item, with one item in the list for each image returned.

For example: If the second item in the list for existList is TRUE, the name of the second image is returned in the second item in the list for imageNameList.


Related topics

ARCreateImage

ARDeleteImage

ARGetImage

ARGetListImage

ARSetImage

FreeAR 

Privileges

All users.

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARGetMultipleImages(
  ARControlStruct *control,
  ARTimestamp changedSince,
  ARNameList *nameList,
  ARBooleanList *existList,
  ARNameList *imageNameList,
  ARTextStringList *imageTypeList,
  ARFilterActionListList *elseListList,
  ARTimestampList *timestampList,
  ARTextStringList *descriptionList,
  ARTextStringList *helpTestList,
  ARAccessNameList *ownerList,
  ARAccessNameList *lastChangedList,
  ARTextStringList *changeDiaryList,
  ARPropListList *objPropListList,
  ARTextStringList *checkSumList,
  ARImageDataList *imageDataList,
  ARStatusList *status)

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.

To specify whether to search for an object's real or resolved name, use the AR_SESS_CONTROL_PROP_API_OVERLAYGROUP variable of the ARSetSessionConfiguration function (see ARSetSessionConfiguration). For calls that use field or view IDs, the search is performed on the real or resolved name of the associated form.

If you do not use the AR_SESS_CONTROL_PROP_API_OVERLAYGROUP variable, the AR System server uses the default overlay group at run time. For information about configuring the default overlay group, see the description for Overlay-mode in Configuration-settings-N-R.

changedSince

A time stamp that limits the images retrieved to those modified after the specified time.

Specify 0 for this parameter to retrieve images with any modification time stamp.

nameList

The names of the images to be retrieved. You can pass the nameList as a NULL or as an empty list, as in:

ARNameList emptyNameList = {0, 0};
   ...
   ARGetMultipleImages(control, changedSince, &emptyNameList, ...)

In this case information is returned for every image that passes the changedSince condition.

Return values

existList

A list of flags and corresponding Boolean values that indicate whether the images exist. The value TRUE means the image exists and FALSE means the image does not exist.

imageNameList

A list of zero or more images that match the criteria defined in the changedSince and nameList parameters. The value is a list with zero items if no images match the specified criteria.

imageTypeList

A list of strings giving the type of the corresponding image in imageNameList.

Specify NULL for this parameter if you do not want to retrieve this value.

timestampList

A list of time stamps that specify the last change to the corresponding image in imageNameList.

Specify NULL for this parameter if you do not want to retrieve this value.

descriptionList

A list of descriptions of the corresponding image in imageNameList.

Specify NULL for this parameter if you do not want to retrieve this value.

helpTextList

A list of help texts for the corresponding image in imageNameList.

Specify NULL for this parameter if you do not want to retrieve this value. This value can be large, so do not reactive it if the program does not need it; for example, if the program is only checking if an object exists.

ownerList

A list of owning users for the corresponding image in imageNameList.

Specify NULL for this parameter if you do not want to retrieve this value.

lastChangedList

A list of users who made the last change to the corresponding image in imageNameList.

Specify NULL for this parameter if you do not want to retrieve this value.

changeDiaryList

A list of change diaries associated with the corresponding image in imageNameList.

Use ARDecodeDiary to parse the change diary into user, time stamp, and text components. The server adds the user making the change and a time stamp when it saves the change diary.

Specify NULL for this parameter if you do not want to retrieve the change diary list. This value can be large, so do not reactive it if the program does not need it; for example, if the program is only checking if an object exists.

objPropListList

A list of server object property lists that correspond to the images in imageNameList. If you set this parameter to NULL, no properties are returned. See Server-object-properties-and-structures.

checkSumList

A list of MD5 hash values retrieved from the database for the corresponding image data in imageDataList. Your program can compute an MD5 hash value and check it against this value to check whether the image data was retrieved correctly.

Specify NULL for this parameter if you do not want to retrieve this value.

imageDataList

An array with the data for the corresponding image in imageNameList. See Images-and-data-structures.

Specify NULL for this parameter if you do not want to retrieve this value.

status

A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error-checking.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*