op_topo_connect()
Abstract
Obtains the object ID of the connector of the requested type and index between the specified source and destination objects.
Syntax
op_topo_connect (src_objid, dst_objid, conn_objmtype, conn_index)
| Argument | Type | Description |
|---|---|---|
src_objid, dst_objid |
Objid |
object IDs of the connected objects [An object ID can be obtained from several KPs in the Id package: op_id_self(), op_id_from_userid(), and op_id_from_name(). In addition, object IDs can be obtained from prior invocations of the Topo package KPs op_topo_parent(), op_topo_child(), op_topo_assoc(), and op_topo_connect().] |
conn_objmtype |
int |
object meta-type of connector [This value is an integer code that specifies the object type of the connection-of-interest (see Table 69 “Object Type Symbolic Constants“ on page 19).] |
conn_index |
int |
numeric index of the connector-of-interest [Connector indices start at 0 and increment by one, up to the number of connectors of that object type less one.] |
Return Type
Objid
Object ID of the specified connector between source and destination objects. The special value represented by the symbolic constant OPC_OBJID_INVALID will be returned if a recoverable error occurs.
Example
/* Verify that a duplex point-to-point link exists between the two nodes. */
link_id = op_topo_connect (src_node_id, dest_node_id, OPC_OBJTYPE_LKDUP, 0);
if (link_id != OPC_OBJID_INVALID)
{
/* The link exists so send the packet. */
op_pk_send (pkptr, MAC_OUT_STREAM);
}
else
{
/* The link does not exist. Destroy the packet and increment counter. */
op_pk_destroy (pkptr);
num_pkts_destroyed++;
}
Details
An object is a connector if it connects two other objects. For example, a packet stream can connect two modules or a link can connect two nodes. Table 22 lists the valid reference object/connector type combinations.
Table 22: Objects and Connector Types
| Source Object Type | Destination Object Type | Connector Type |
|---|---|---|
| site (subnet; fixed node) | site | path |
| fixed node | fixed node | link |
| module (processor, queue, and so on) | module | stream & statistic wire |
| transmitter (pt-pt, bus, radio) | receiver (pt-pt, bus, radio) | link |
| bus transmitter | bus link | tap |
| bus link | bus receiver | tap |
Mobile and satellite nodes do not support connectors, since they cannot be connected to a point-to-point or bus link.
Purpose
Provides a mechanism to obtain an object ID of an object that is located between two other objects. This is typically a useful function when a process needs to obtain or assign attributes that belong to a connector object. For example, a process in a transmitting node may need to change the bit error rate of a link to a particular receiving node. A call to op_topo_connect() would provide the object ID of the link connecting the two nodes. A call to op_ima_obj_attr_set() would set the new bit error rate value.
Errors
- Recoverable Error: Source object ID (<src_objid>) is out-of-range.
- Recoverable Error: Destination object ID (<dst_objid>) is out-of-range.
- Recoverable Error: Object meta-type (<conn_objmtype>) is unrecognized.
- Recoverable Error: Object index (<conn_index>) is out-of-range.
- Recoverable Error: Source object ID (<src_objid>) refers to a restricted object.
- Recoverable Error: Destination object ID (<dst_objid>) refers to a restricted object.
Reference
- Use the KP op_topo_connect_count() to determine the number of connectors between two objects
- Use the KP op_ima_obj_attr_get() to obtain the value of an object’s attribute
- Use the KP op_ima_obj_attr_set() to assign the value of an object’s attribute
- Use the KP op_topo_object() to obtain the object ID of an object