DATA RETRIEVAL
====================================================================

EXAMPLES
--------------------------------------------------------------------

Main parts are configuration, data query and data processing.


Configuration for MySQL:

<?php
$apiFile = 'icinga-api/IcingaApi.php';
$idoConfig = array (
	'type'			=> 'mysql',
	'host'			=> 'localhost',
	'database'		=> 'icinga',
	'user'			=> 'icinga',
	'password'		=> 'icinga',
	'table_prefix'	=> 'icinga_',
);

require_once($apiFile);

$api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig);
?>



Data processing:

Output of all queried host names:

<?php
foreach ($apiRes as $apiHandle) {
	$row = $apiHandle->getRow();
	echo $row->HOST_NAME;
}
?>



Full example for host names, addresses and statuses of hosts starting with 'linux':

<?php
$apiFile = 'icinga-api/IcingaApi.php';
$idoConfig = array (
	'type'			=> 'mysql',
	'host'			=> 'localhost',
	'database'		=> 'icinga',
	'user'			=> 'icinga',
	'password'		=> 'icinga',
	'table_prefix'	=> 'icinga_',
);

require_once($apiFile);

$api = IcingaApi::getConnection(IcingaApi::CONNECTION_IDO, $idoConfig);

$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_HOST)
	->setResultColumns(array('HOST_NAME', 'HOST_ADDRESS', 'HOST_CURRENT_STATE'))
	->setSearchFilter('HOST_NAME', 'linux%', IcingaApi::MATCH_LIKE)
	->setSearchOrder('HOST_NAME')
	->fetch();

foreach ($apiRes as $apiHandle) {
	$row = $apiHandle->getRow();
	echo $row->HOST_NAME . ' ' . $row->HOST_ADDRESS . ' ' . $row->HOST_CURRENT_STATE . "<br/>\n";
}
?>



More examples for data query:

<?php
/*
 * query for program date
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_PROGRAM)
	->setResultColumns('PROGRAM_DATE)
	->fetch();

/*
 * query for contact group by contact
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_CONTACTGROUP')
	->setResultColumns('CONTACTGROUP_NAME')
	->setSearchFilter('CONTACT_NAME', 'nagios-admin')
	->fetch();

/*
 * query for host status
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_HOST)
	->setResultColumns(array('HOST_NAME', 'HOST_ALIAS', 'HOST_DISPLAY_NAME', 'HOST_ADDRESS', 'HOST_OUTPUT', 'HOST_PERFDATA', 'HOST_CURRENT_STATE', 'HOST_CURRENT_CHECK_ATTEMPT', 'HOST_MAX_CHECK_ATTEMPTS', 'HOST_LAST_CHECK', 'HOST_LAST_STATE_CHANGE', 'HOST_CHECK_TYPE', 'HOST_LATENCY', 'HOST_EXECUTION_TIME', 'HOST_NEXT_CHECK', 'HOST_HAS_BEEN_CHECKED', 'HOST_LAST_HARD_STATE_CHANGE', 'HOST_LAST_NOTIFICATION', 'HOST_STATE_TYPE', 'HOST_IS_FLAPPING', 'HOST_PROBLEM_HAS_BEEN_ACKNOWLEDGED', 'HOST_SCHEDULED_DOWNTIME_DEPTH', 'HOST_STATUS_UPDATE_TIME'))
	->setSearchFilter('CONTACTGROUP_NAME', '%', IcingaApi::MATCH_LIKE)
	->setSearchFilter('HOST_NAME', 'localhost')
	->setSearchGroup('HOST_ID')
	->setSearchOrder('HOST_NAME')
	->fetch();

/*
 * query for host execution time and latency
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_HOST)
	->setResultColumns(array('HOST_EXECUTION_TIME_MIN', 'HOST_EXECUTION_TIME_AVG', 'HOST_EXECUTION_TIME_MAX', 'HOST_LATENCY_MIN', 'HOST_LATENCY_AVG', 'HOST_LATENCY_MAX'))
	->setSearchFilter('CONTACTGROUP_NAME', '%', IcingaApi::MATCH_LIKE)
	->setSearchFilter('HOST_NAME', 'localhost')
	->setSearchGroup('HOST_CONFIG_TYPE')
	->fetch();

/*
 * query for active hosts
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_HOST)
	->setSearchType(IcingaApi::SEARCH_TYPE_COUNT)
	->setResultColumns('HOST_OBJECT_ID')
	->setSearchFilter('CONTACTGROUP_NAME', '%', IcingaApi::MATCH_LIKE)
	->setSearchFilter('HOST_ACTIVE_CHECKS_ENABLED', 1)
	->setSearchGroup('HOST_IS_ACTIVE')
	->fetch();

/*
 * query for service execution time and latency
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_SERVICE)
	->setResultColumns(array('SERVICE_EXECUTION_TIME_MIN', 'SERVICE_EXECUTION_TIME_AVG', 'SERVICE_EXECUTION_TIME_MAX', 'SERVICE_LATENCY_MIN', 'SERVICE_LATENCY_AVG', 'SERVICE_LATENCY_MAX'))
	->setSearchFilter(array(
		array('CONTACTGROUP_NAME', '%', IcingaApi::MATCH_LIKE),
		array('HOST_NAME', 'localhost'),
		array('SERVICE_NAME', 'PING'),
	))
	->fetch();

/*
 * query for service status
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_SERVICE)
	->setResultColumns(array('HOST_STATUS_ALL', 'SERVICE_NAME', 'SERVICE_DISPLAY_NAME', 'SERVICE_NOTIFICATIONS_ENABLED', 'SERVICE_OUTPUT', 'SERVICE_PERFDATA', 'SERVICE_CURRENT_STATE', 'SERVICE_CURRENT_CHECK_ATTEMPT', 'SERVICE_MAX_CHECK_ATTEMPTS', 'SERVICE_LAST_CHECK', 'SERVICE_LAST_STATE_CHANGE', 'SERVICE_CHECK_TYPE', 'SERVICE_LATENCY', 'SERVICE_EXECUTION_TIME', 'SERVICE_NEXT_CHECK', 'SERVICE_HAS_BEEN_CHECKED', 'SERVICE_LAST_HARD_STATE_CHANGE', 'SERVICE_LAST_NOTIFICATION', 'SERVICE_STATE_TYPE', 'SERVICE_IS_FLAPPING', 'SERVICE_PROBLEM_HAS_BEEN_ACKNOWLEDGED', 'SERVICE_SCHEDULED_DOWNTIME_DEPTH', 'SERVICE_STATUS_UPDATE_TIME'))
	->setSearchFilter(array(
		array('CONTACTGROUP_NAME', '%', IcingaApi::MATCH_LIKE),
		array('HOST_NAME', 'localhost'),
		array('SERVICE_NAME', 'PING'),
	))
	->setSearchGroup('SERVICE_ID')
	->setSearchOrder(array('HOST_NAME', 'SERVICE_NAME'))
	->setSearchLimit(15)
	->fetch();

/*
 * query for config variables (position 10 to 30)
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_CONFIG)
	->setResultColumns('CONFIG_VAR_NAME')
	->setResultColumns('CONFIG_VAR_VALUE')
	->setSearchFilter('CONFIG_VAR_NAME', '%file', IcingaApi::MATCH_LIKE)
	->setSearchOrder('CONFIG_VAR_NAME')
	->setSearchLimit(10,20)
	->fetch();

/*
 * query for host status summary
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_HOST_STATUS_SUMMARY)
	->fetch();

/*
 * query for service status summary
 */
$apiRes = $api->createSearch()
	->setSearchTarget(IcingaApi::TARGET_SERVICE_STATUS_SUMMARY)
	->fetch();
?>



COMMANDS
--------------------------------------------------------------------

setSearchTarget(<SEARCH_TARGET>)
--------------------------------------------------------------------

currently available search targets are:

IcingaApi::TARGET_CONFIG
IcingaApi::TARGET_CONTACTGROUP
IcingaApi::TARGET_CUSTOMVARIABLE
IcingaApi::TARGET_HOST
IcingaApi::TARGET_HOSTGROUP
IcingaApi::TARGET_HOSTGROUP_SUMMARY
IcingaApi::TARGET_HOST_PARENTS
IcingaApi::TARGET_HOSTSTATUS
IcingaApi::TARGET_HOST_STATUS_HISTORY
IcingaApi::TARGET_HOST_STATUS_SUMMARY
IcingaApi::TARGET_HOST_TIMES
IcingaApi::TARGET_LOG
IcingaApi::TARGET_NOTIFICATIONS
IcingaApi::TARGET_PROGRAM
IcingaApi::TARGET_SERVICE
IcingaApi::TARGET_SERVICEGROUP
IcingaApi::TARGET_SERVICEGROUP_SUMMARY
IcingaApi::TARGET_SERVICESTATUS
IcingaApi::TARGET_SERVICE_STATUS_HISTORY
IcingaApi::TARGET_SERVICE_STATUS_SUMMARY
IcingaApi::TARGET_SERVICE_TIMES
IcingaApi::TARGET_TIMEPERIOD



setResultColumns(<COLUMNS>)
--------------------------------------------------------------------

currently available columns:

// Program information
'PROGRAM_DATE'
'PROGRAM_INSTANCE_ID'
'PROGRAM_VERSION'

// Hostgroup data
'HOSTGROUP_ALIAS'
'HOSTGROUP_ID'
'HOSTGROUP_INSTANCE_ID'
'HOSTGROUP_NAME'
'HOSTGROUP_OBJECT_ID'
'HOSTGROUP_SUMMARY_COUNT'

// Servicegroup data
'SERVICEGROUP_ALIAS'
'SERVICEGROUP_ID'
'SERVICEGROUP_INSTANCE_ID'
'SERVICEGROUP_NAME'
'SERVICEGROUP_OBJECT_ID'
'SERVICEGROUP_SUMMARY_COUNT'

// Contactgroup data
'CONTACTGROUP_ALIAS'
'CONTACTGROUP_ID'
'CONTACTGROUP_INSTANCE_ID'
'CONTACTGROUP_NAME'
'CONTACTGROUP_OBJECT_ID'

// Contact data
'CONTACT_NAME'

// Timeperiod data
'TIMEPERIOD_ALIAS'
'TIMEPERIOD_DAY'
'TIMEPERIOD_ENDTIME'
'TIMEPERIOD_ID'
'TIMEPERIOD_INSTANCE_ID'
'TIMEPERIOD_NAME'
'TIMEPERIOD_OBJECT_ID'
'TIMEPERIOD_STARTTIME'

// Customvariable data
'CUSTOMVARIABLE_ID'
'CUSTOMVARIABLE_INSTANCE_ID'
'CUSTOMVARIABLE_MODIFIED'
'CUSTOMVARIABLE_NAME'
'CUSTOMVARIABLE_OBJECT_ID'
'CUSTOMVARIABLE_VALUE'
'CUSTOMVARIABLE_UPDATETIME'

// Host data
'HOST_ACTION_URL'
'HOST_ACTIVE_CHECKS_ENABLED'
'HOST_ACTIVE_CHECKS_ENABLED'
'HOST_ADDRESS'
'HOST_ALIAS'
'HOST_ALL'
'HOST_CHECK_TYPE'
'HOST_CHILD_NAME'
'HOST_CHILD_OBJECT_ID'
'HOST_CONFIG_TYPE'
'HOST_CURRENT_CHECK_ATTEMPT'
'HOST_CURRENT_STATE'
'HOST_DISPLAY_NAME'
'HOST_EVENT_HANDLER_ENABLED'
'HOST_EXECUTION_TIME'
'HOST_EXECUTION_TIME_AVG'
'HOST_EXECUTION_TIME_MAX'
'HOST_EXECUTION_TIME_MIN'
'HOST_FAILURE_PREDICTION_ENABLED'
'HOST_FLAP_DETECTION_ENABLED'
'HOST_FRESHNESS_CHECKS_ENABLED'
'HOST_FRESHNESS_THRESHOLD'
'HOST_HAS_BEEN_CHECKED'
'HOST_ICON_IMAGE'
'HOST_ICON_IMAGE_ALT'
'HOST_ID'
'HOST_INSTANCE_ID'
'HOST_IS_ACTIVE'
'HOST_IS_FLAPPING'
'HOST_LAST_CHECK'
'HOST_LAST_HARD_STATE_CHANGE'
'HOST_LAST_NOTIFICATION'
'HOST_LAST_STATE_CHANGE'
'HOST_LATENCY'
'HOST_LATENCY_AVG'
'HOST_LATENCY_MAX'
'HOST_LATENCY_MIN'
'HOST_LONG_OUTPUT'
'HOST_MAX_CHECK_ATTEMPTS'
'HOST_NAME'
'HOST_NEXT_CHECK'
'HOST_NOTES'
'HOST_NOTES_URL'
'HOST_NOTIFICATIONS_ENABLED'
'HOST_OBJECT_ID'
'HOST_OBSESS_OVER_HOST'
'HOST_OUTPUT'
'HOST_PARENT_NAME'
'HOST_PARENT_OBJECT_ID'
'HOST_PASSIVE_CHECKS_ENABLED'
'HOST_PERFDATA'
'HOST_PROBLEM_HAS_BEEN_ACKNOWLEDGED'
'HOST_PROCESS_PERFORMANCE_DATA'
'HOST_RETAIN_NONSTATUS_INFORMATION'
'HOST_RETAIN_STATUS_INFORMATION'
'HOST_SCHEDULED_DOWNTIME_DEPTH'
'HOST_STATE'
'HOST_STATE_COUNT'
'HOST_STATE_TYPE'
'HOST_STATUS_ALL'
'HOST_STATUS_UPDATE_TIME'

// Service data
'SERVICE_ACTION_URL'
'SERVICE_ACTIVE_CHECKS_ENABLED'
'SERVICE_ALL'
'SERVICE_CHECK_TYPE'
'SERVICE_CONFIG_TYPE'
'SERVICE_CURRENT_CHECK_ATTEMPT'
'SERVICE_CURRENT_STATE'
'SERVICE_DISPLAY_NAME'
'SERVICE_EVENT_HANDLER_ENABLED'
'SERVICE_EXECUTION_TIME'
'SERVICE_EXECUTION_TIME_AVG'
'SERVICE_EXECUTION_TIME_MAX'
'SERVICE_EXECUTION_TIME_MIN'
'SERVICE_FAILURE_PREDICTION_ENABLED'
'SERVICE_FLAP_DETECTION_ENABLED'
'SERVICE_HAS_BEEN_CHECKED'
'SERVICE_ICON_IMAGE'
'SERVICE_ICON_IMAGE_ALT'
'SERVICE_ID'
'SERVICE_INSTANCE_ID'
'SERVICE_IS_ACTIVE'
'SERVICE_IS_FLAPPING'
'SERVICE_LAST_CHECK'
'SERVICE_LAST_HARD_STATE_CHANGE'
'SERVICE_LAST_NOTIFICATION'
'SERVICE_LAST_STATE_CHANGE'
'SERVICE_LATENCY'
'SERVICE_LATENCY_AVG'
'SERVICE_LATENCY_MAX'
'SERVICE_LATENCY_MIN'
'SERVICE_LONG_OUTPUT'
'SERVICE_MAX_CHECK_ATTEMPTS'
'SERVICE_NAME'
'SERVICE_NEXT_CHECK'
'SERVICE_NOTES'
'SERVICE_NOTES_URL'
'SERVICE_NOTIFICATIONS_ENABLED'
'SERVICE_OBJECT_ID'
'SERVICE_OBSESS_OVER_SERVICE'
'SERVICE_OUTPUT'
'SERVICE_PASSIVE_CHECKS_ENABLED'
'SERVICE_PERFDATA'
'SERVICE_PROBLEM_HAS_BEEN_ACKNOWLEDGED'
'SERVICE_RETAIN_NONSTATUS_INFORMATION'
'SERVICE_RETAIN_STATUS_INFORMATION'
'SERVICE_SCHEDULED_DOWNTIME_DEPTH'
'SERVICE_STATE_TYPE'
'SERVICE_STATUS_ALL'
'SERVICE_STATUS_UPDATE_TIME'

// Config vars
'CONFIG_VAR_ID'
'CONFIG_VAR_INSTANCE_ID'
'CONFIG_VAR_NAME'
'CONFIG_VAR_VALUE'

// Logentries
'LOG_DATA'
'LOG_ENTRY_TIME'
'LOG_ENTRY_TIME_USEC'
'LOG_ID'
'LOG_INFERRED_DATA'
'LOG_INSTANCE_ID'
'LOG_REALTIME_DATA'
'LOG_TIME'
'LOG_TYPE'

// Statehistory
'STATEHISTORY_CURRENT_CHECK_ATTEMPT'
'STATEHISTORY_ID'
'STATEHISTORY_INSTANCE_ID'
'STATEHISTORY_LAST_HARD_STATE'
'STATEHISTORY_LAST_STATE'
'STATEHISTORY_LONG_OUTPUT'
'STATEHISTORY_MAX_CHECK_ATTEMPTS'
'STATEHISTORY_OBJECT_ID'
'STATEHISTORY_OUTPUT'
'STATEHISTORY_STATE'
'STATEHISTORY_STATE_CHANGE'
'STATEHISTORY_STATE_TIME'
'STATEHISTORY_STATE_TIME_USEC'
'STATEHISTORY_STATE_TYPE'

// Notifications
'NOTIFICATION_ENDTIME'
'NOTIFICATION_ENDTIME_USEC'
'NOTIFICATION_ESCALATED'
'NOTIFICATION_ID'
'NOTIFICATION_INSTANCE_ID'
'NOTIFICATION_LONG_OUTPUT'
'NOTIFICATION_NOTIFIED'
'NOTIFICATION_OBJECT_ID'
'NOTIFICATION_OBJECTTYPE_ID'
'NOTIFICATION_OUTPUT'
'NOTIFICATION_REASON'
'NOTIFICATION_STARTTIME'
'NOTIFICATION_STARTTIME_USEC'
'NOTIFICATION_STATE'
'NOTIFICATION_TYPE'



setSearchFilter(<COLUMN>, <PATTERN>, [MATCH_TYPE])
setSearchFilter(array(<COLUMN>, <PATTERN>, [MATCH_TYPE]))
setSearchFilter(
	array(
		array(<COLUMN>, <PATTERN>, [MATCH_TYPE]),
		array(<COLUMN>, <PATTERN>, [MATCH_TYPE]),
		...
		array(<COLUMN>, <PATTERN>, [MATCH_TYPE])
	)
);
--------------------------------------------------------------------

available match types:

IcingaApi::MATCH_EXACT (default)
IcingaApi::MATCH_GREATER_OR_EQUAL
IcingaApi::MATCH_GREATER_THAN
IcingaApi::MATCH_LESS_OR_EQUAL
IcingaApi::MATCH_LESS_THAN
IcingaApi::MATCH_LIKE



setSearchFilterAppendix(<FILTER_STATEMENT>, [SEARCH_AGGREGATOR])
--------------------------------------------------------------------

example for FILTER_STATEMENT:

'${CONTACT_NAME} like \'%admin\''


available search aggregators:

IcingaApi::SEARCH_AND
IcingaApi::SEARCH_OR



setSearchGroup(<COLUMNS>)
--------------------------------------------------------------------

columns as seen under setResultColumns()



setSearchOrder(<COLUMN>, [DIRECTION])
--------------------------------------------------------------------

available directions:

'asc'
'desc'



setSearchLimit(<LENGTH>)
setSearchLimit(<START>, <LENGTH>)
--------------------------------------------------------------------

START and LENGTH are integer values