op_ima_obj_pos_query_proc_set()
Abstract
Sets a callback to return the position of a mobile site that is not following a trajectory or vector.
Syntax
op_ima_obj_pos_query_proc_set (site_objid, callback, state_ptr, lat_long_unit)
| Argument | Type | Description |
|---|---|---|
site_objid |
Objid |
object ID of the site-of-interest (node or subnet) [A site object ID can be obtained from several KPs in the Id and Topo packages: op_topo_parent(), op_topo_child(), op_id_from_userid(), and op_id_from_name().] |
callback |
SimT_Ima_Obj_Position_Query_Proc |
procedure to be called whenever a position is needed for the object-of-interest |
state_ptr |
void* |
user-defined data passed to the callback procedure |
lat_long_unit |
OpT_Ima_Obj_Position_Unit_Type |
the type of units used by latitude and longitude values (one of the values given in Table 68 "Object Position Unit Type Symbolic Constants" on page 19) [This cannot change during the simulation for a given site.] |
Return Type
Compcode
OPC_COMPCODE_FAILURE if an error occurs (see Errors section); OPC_COMPCODE_SUCCESS otherwise.
Example
void straight_line_ascend (SimT_Objid site_id, void * state_ptr,
double prev_time, double prev_latitude, double prev_longitude,
double prev_altitude, double cur_time, double * lat_ptr,
double * long_ptr, double * alt_in_meters_ptr)
{
/* increase altitude 1 meter/second */
*alt_in_meters_ptr = prev_altitude + (cur_time-prev_time) * 1.0;
*lat_ptr = prev_latitude;
*long_ptr = prev_longitude;
}
[...]
op_ima_obj_pos_query_proc_set (mobile_node_id, straight_line_ascend,
OPC_NIL, OpC_Ima_Obj_Position_Unit_Kilometers);
Details
callback is a custom procedure that computes a new three-dimensional position for a site given a requested time and the site’s previous position and time. The callback prototype is:
typedef void
(*SimT_Ima_Obj_Position_Query_Proc)(SimT_Objid site_id,
void * state_ptr, double prev_time, double prev_latitude,
double prev_longitude, double prev_altitude_in_meters,
double request_time, double * lat_ptr, double * long_ptr,
double * alt_in_meters_ptr);
request_time will be the current simulation time or some future time. Latitude and longitude are given (and must be returned) in the units specified by the lat_long_unit argument when the callback was registered. The calculated position should be returned in the areas specified by lat_ptr, long_ptr, and alt_in_meters_ptr.
Note: When the Simulation Kernel invokes this callback, the previous time and position values passed to the callback will not necessarily correspond to the previous invocation. Because the Simulation Kernel only caches the returned values when computing the object’s current position, the previous values will instead correspond to the last invocation for which request_time was the then-current simulation time.
WARNING: Do not attempt to get a site’s current position with op_ima_obj_pos_get() or op_ima_obj_attr_get() from within the callback; an infinite loop will result.
Setting callback to an OPC_NIL pointer will stop the Simulation Kernel from invoking callbacks (in which case the Kernel will just use the current position of the node).
Purpose
Normally, the Simulation Kernel uses whatever position was last set for nodes that aren’t following a trajectory or vector. This KP registers a callback for a specific mobile site (node or subnet) that enables the Simulation Kernel to obtain an exact position whenever needed.
Errors
- Recoverable Error: Object ID (
<site_objid>) is out-of-range. - Recoverable Error: Object ID (
<site_objid>) refers to a restricted object. - Recoverable Error: Unable to set position query callback for object (
<site_objid>) because it is not a mobile node or subnet (object type is<type_name>) - Recoverable Error: Unable to set position query callback for object (
<site_objid>) because it uses a trajectory - Recoverable Error: Unable to set position query callback for object (
<site_objid>) because the unit argument is invalid (<lat_long_unit>)
Reference
- Use the KP op_ima_obj_pos_get() to get the global position-related attributes of a site.
- Use the KP op_ima_obj_attr_get_dbl() to obtain a single position-related attribute of a site.