All RAD objects, which are represented in the ADR IDL as <interfaces>, are found by searching the RAD namespace. The key point to note is that to access a RAD object, you should use the list and lookup functions provided by a module's client binding library (<module>_<interface>__rad_list(), <module>_<interface>__rad_lookup(). These functions also provide the option to do either strict or relaxed versioning.
Using the functions specific to the interface automatically provides the base name and version details for interface instances. Those names are structured as follows:
<domain name>:type=<interface name>[,optional additional key value pairs]
The <domain name> and the <interface name> are automatically derived from the ADR IDL definition and are stored in the module binding.
As noted in the previous section, a module's client binding provides a search function for each interface defined in the form: <module>_<interface>__rad_list() where a pattern (glob or regex) may be provided to narrow the search further within objects of a certain interface type.
In addition, libradclient does provide a function, rc_list(), where the caller can provide the entire name/pattern and version information to search for.
If a module developer creates a “singleton” to represent an interface, then this can be accessed very simply. For instance, the zonemgr module defines a singleton interface: ZoneInfo. It contains information about the zone which contains the RAD instance with which we are communicating.
Example 3-3 Obtaining a Reference to a Singleton
#include <rad/radclient.h>
#include<rad/client/1/zonemgr.h>
rc_instance_t *inst;
rc_err_t status;
char *name;
rc_conn_t *conn = rc_connect_unix(NULL, B_TRUE, NULL);
if (conn !=NULL) {
status = zonemgr_ZoneInfo__rad_lookup(conn, B_TRUE, &inst, 0);
if(status == RCE_OK) {
status =zonemgr_ZoneInfo_get_name(inst, &name);
if (status ==RCE_OK)
printf("Zone name: %s\n", name);
}
}
We have connected to the local RAD instance and obtained a remote object reference directly using the lookup function provided by the zonemgr binding. Once we have the remote reference we can access properties with a <module>_<interface>_get_<property>() function.
Most interfaces contain more than one instance of the interface. For instance, the zonemgr module defines a Zone interface and there is an instance for each zone on the system. A module provides a list function for each of its interfaces in the form: <module>_<interface>__rad_list().
Example 3-4 Listing Interface Instances
#include<rad/radclient.h>
#include<rad/radclient_basetypes.h>
#include<rad/client/1/zonemgr.h>
rc_err_t status;
adr_name_t **name_list;
int name_count;
rc_conn_t *conn = rc_connect_unix(NULL, B_TRUE, NULL);
if (conn !=NULL) {
status = zonemgr_Zone__rad_list(conn, B_TRUE, NS_GLOB, &name_list,
&name_count, 0);
if(status == RCE_OK) {
for (int i =0; i < name_count; i++) {
char*name =adr_name_tostr(name_list[i]);
printf("%s\n", name);
}
name_array_free(name_list, name_count);
}
}
Names (in the form of an adr_name_t reference) are returned when using the list mechanism detailed above. Once we have a "name" we can obtain a remote object reference easily:
Example 3-5 Obtaining a Remote Object Reference from a Name
#include <rad/radclient.h>
#include <rad/radclient_basetypes.h>
#include<rad/client/1/zonemgr.h>
rc_err_t status;
adr_name_t **name_list;
rc_instance_t *zone_inst;
int name_count;
rc_conn_t *conn = rc_connect_unix(NULL, B_TRUE, NULL);
if (conn != NULL) {
status = zonemgr_Zone__rad_list(conn, B_TRUE, NS_GLOB, &name_list,
&name_count, 0);
if (status == RCE_OK) {
status = rc_lookup(conn, name_list[0],
NULL, B_TRUE, &zone_inst);
if (status == RCE_OK) {
char *name;
status = zonemgr_Zone_get_name(zone_inst, &name);
if (status == RCE_OK)
printf("Zone name: %s\n",
name);
free(name);
}
name_array_free(name_list, name_count);
}
}
Clearly, the last example is not a very realistic use case. Rarely are we going to want to just pick a (semi-random) zone from a list and interact with it. More often than not we'll be looking for a zone which has a particular name or id or maybe a set of zones where the names all match some kind of pattern. The key idea to bear in mind is that you can extend the use of the “list” functionality to restrict the results. For instance, if zones are uniquely identified by a key: “name”, then we can find a zone with name “test-0” as follows:
Example 3-6 Using Glob Patterns
#include <rad/radclient.h>
#include <rad/radclient_basetypes.h>
#include <rad/client/1/zonemgr.h>
rc_err_t status;
adr_name_t **name_list;
int name_count;
rc_conn_t *conn = rc_connect_unix(NULL, B_TRUE, NULL);
if (conn != NULL) {
status = zonemgr_Zone__rad_list(conn, B_TRUE, NS_GLOB, B_TRUE, &name_list,
&name_count, 1, "name", "test-0");
if (status == RCE_OK) {
for (int i = 0; i < name_count; i++) {
const char *name = adr_name_tostr(name_list[i]);
printf("%s\n", name);
}
name_array_free(name_list, name_count);
}
}
We've already seen how we can use glob pattern searching to find a zone with a specific name. We can also use a glob pattern to find zones with wildcard pattern matching. Keys or Values in the pattern may contain "*" which is interpreted as expected. For instance ,if we wanted to find all zones with a name which begins with "test":
Example 3-7 Using Glob Patterns with Wildcards
#include <rad/radclient.h>
#include <rad/radclient_basetypes.h>
#include <rad/client/1/zonemgr.h>
rc_err_t status;
adr_name_t **name_list;
int name_count;
rc_conn_t *conn = rc_connect_unix(NULL, B_TRUE, NULL);
if (conn != NULL) {
status = zonemgr_Zone__rad_list(conn, B_TRUE, NS_GLOB, &name_list,
&name_count, 1, "name", "test*");
if (status == RCE_OK) {
for (int i = 0; i < name_count; i++) {
const char *name = adr_name_tostr(name_list[i]);
printf("%s\n", name);
}
name_array_free(name_list, name_count);
}
}
We can also take advantage of RAD's ERE (Extended Regular Expression) search capabilities. If we wanted to find only zones with name "test-0" or "test-1", then:
Example 3-8 Using Regex Patterns#include <rad/radclient.h>
#include <rad/radclient_basetypes.h>
#include <rad/client/1/zonemgr.h>
rc_err_t status;
adr_name_t **name_list;
int name_count;
rc_conn_t *conn = rc_connect_unix(NULL, B_TRUE, NULL);
if (conn != NULL) {
status = zonemgr_Zone__rad_list(conn, B_TRUE, NS_REGEX,
&name_list, &name_count, 1, "name", "test-0|test-1");
if (status == RCE_OK) {
for (int i = 0; i < name_count; i++) {
const char *name = adr_name_tostr(name_list[i]);
printf("%s\n", name);
}
name_array_free(name_list, name_count);
}
}
The key and the value must be valid Extended Regular Expressions as determined by the instance of RAD to which you are connected. This means that the expression is compiled and executed in the server.