odocprovider-1 - API for accessing Solaris Online Docs
#include <rad/client/1/odocprovider.h>
cc [ flag... ] file... -lodocprovider1_client [ library... ]
interface ODocProvider
rc_err_t odocprovider_ODocProvider_getDocument(rc_instance_t *inst,
const char *href,
boolean_t *resolveTargets,
const char *language,
odocprovider_Document_t **result,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_resolveTargets(rc_instance_t *inst,
const char **hrefs,
int hrefs_count,
const char *language,
odocprovider__rad_dict_string_string_t **result,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_getTargets(rc_instance_t *inst,
const char *topicGroup,
const char *navigationGroup,
const char *lang,
odocprovider_Target_t ***result,
int *result_cnt,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_getTopicGroups(rc_instance_t *inst,
boolean_t *includeHidden,
const char *language,
odocprovider__rad_dict_string_string_t **result,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_search(rc_instance_t *inst,
const char *query,
int *limit,
const char *language,
odocprovider_SearchResult_t ***result,
int *result_cnt,
odocprovider_Error_t **error);
Enumerated Types
enum ErrorType
typedef enum odocprovider_ErrorType {
OET_ERR_DOCUMENT_NOT_FOUND = 0,
OET_ERR_INVALID_HREF = 1,
OET_ERR_INVALID_LANG = 2,
OET_ERR_SEARCH_UNAVAILABLE = 3,
OET_ERR_UNABLE_ACCESS_FILES = 4,
} odocprovider_ErrorType_t;
Structured Types
struct Error
typedef struct odocprovider_Error odocprovider_Error_t;
struct odocprovider_Error {
odocprovider_ErrorType_t oe_errorType;
char *oe_message;
};
void odocprovider_Error_free(odocprovider_Error_t *in);
struct Document
typedef struct odocprovider_Document odocprovider_Document_t;
struct odocprovider_Document {
char *od_content;
odocprovider_Target_t *od_target;
odocprovider__rad_dict_string_string_t *od_resolvedTargets;
};
void odocprovider_Document_free(odocprovider_Document_t *in);
struct Target
typedef struct odocprovider_Target odocprovider_Target_t;
struct odocprovider_Target {
char *ot_href;
odocprovider_Target_t **ot_targets;
int ot_targets_count;
char *ot_topicGroup;
char *ot_title;
char *ot_navigationGroup;
char **ot_labels;
int ot_labels_count;
};
void odocprovider_Target_free(odocprovider_Target_t *in);
struct SearchResult
typedef struct odocprovider_SearchResult
odocprovider_SearchResult_t;
struct odocprovider_SearchResult {
odocprovider_Target_t *osr_target;
double osr_score;
};
void odocprovider_SearchResult_free(odocprovider_SearchResult_t *in);
Dictionaries
Dictionary { string : string }
typedef struct base_rad_dict
odocprovider__rad_dict_string_string_t;
ODOCPROVIDER-1(3rad) RAD Module Definitions ODOCPROVIDER-1(3rad)
NAME
odocprovider - API for accessing Solaris Online Docs
SYNOPSIS
#include <rad/client/1/odocprovider.h>
cc [ flag... ] file... -lodocprovider1_client [ library... ]
interface ODocProvider
rc_err_t odocprovider_ODocProvider_getDocument(rc_instance_t *inst,
const char *href,
boolean_t *resolveTargets,
const char *language,
odocprovider_Document_t **result,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_resolveTargets(rc_instance_t *inst,
const char **hrefs,
int hrefs_count,
const char *language,
odocprovider__rad_dict_string_string_t **result,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_getTargets(rc_instance_t *inst,
const char *topicGroup,
const char *navigationGroup,
const char *lang,
odocprovider_Target_t ***result,
int *result_cnt,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_getTopicGroups(rc_instance_t *inst,
boolean_t *includeHidden,
const char *language,
odocprovider__rad_dict_string_string_t **result,
odocprovider_Error_t **error);
rc_err_t odocprovider_ODocProvider_search(rc_instance_t *inst,
const char *query,
int *limit,
const char *language,
odocprovider_SearchResult_t ***result,
int *result_cnt,
odocprovider_Error_t **error);
Enumerated Types
enum ErrorType
typedef enum odocprovider_ErrorType {
OET_ERR_DOCUMENT_NOT_FOUND = 0,
OET_ERR_INVALID_HREF = 1,
OET_ERR_INVALID_LANG = 2,
OET_ERR_SEARCH_UNAVAILABLE = 3,
OET_ERR_UNABLE_ACCESS_FILES = 4,
} odocprovider_ErrorType_t;
Structured Types
struct Error
typedef struct odocprovider_Error odocprovider_Error_t;
struct odocprovider_Error {
odocprovider_ErrorType_t oe_errorType;
char *oe_message;
};
void odocprovider_Error_free(odocprovider_Error_t *in);
struct Document
typedef struct odocprovider_Document odocprovider_Document_t;
struct odocprovider_Document {
char *od_content;
odocprovider_Target_t *od_target;
odocprovider__rad_dict_string_string_t *od_resolvedTargets;
};
void odocprovider_Document_free(odocprovider_Document_t *in);
struct Target
typedef struct odocprovider_Target odocprovider_Target_t;
struct odocprovider_Target {
char *ot_href;
odocprovider_Target_t **ot_targets;
int ot_targets_count;
char *ot_topicGroup;
char *ot_title;
char *ot_navigationGroup;
char **ot_labels;
int ot_labels_count;
};
void odocprovider_Target_free(odocprovider_Target_t *in);
struct SearchResult
typedef struct odocprovider_SearchResult
odocprovider_SearchResult_t;
struct odocprovider_SearchResult {
odocprovider_Target_t *osr_target;
double osr_score;
};
void odocprovider_SearchResult_free(odocprovider_SearchResult_t *in);
Dictionaries
Dictionary { string : string }
typedef struct base_rad_dict
odocprovider__rad_dict_string_string_t;
DESCRIPTION
API com.oracle.solaris.rad.odocprovider [1]
Solaris Online Docs module utilizes private odoc Python APIs to serve
documentation created using odoctool into WebUI application.
Href.
In order to identify documents in Solaris Online Docs we use href
(handle reference) locator which has following form:
bundleId:docId#linkId. Part linkId is optional but # should be present
all times. All occurences of word href in this document refer to this
locator.
INTERFACES
interface ODocProvider
Solaris Online Docs API.
ODocProvider interface allows client to:
o Fetch available documents by their known href.
o Resolve one or more hrefs.
o Retrieve all locally available targets.
o Retrieve all locally available topic groups.
o Search locally indexed document content.
ODocProvider Methods
rc_err_t odocprovider_ODocProvider_getDocument(rc_instance_t *inst,
const char *href,
boolean_t *resolveTargets,
const char *language,
odocprovider_Document_t **result,
odocprovider_Error_t **error);
Fetch the document identified by href and optionally resolve
all targets in its content.
Arguments:
inst -- RAD instance
href -- Href of document to retrieve.
resolveTargets (nullable) -- If true then all targets in the
retrieved document content will be resolved and resolutions
stored in resolvedTargets. If null it defaults to false.
language (nullable) -- Language variant.
result
error
rc_err_t odocprovider_ODocProvider_resolveTargets(rc_instance_t *inst,
const char **hrefs,
int hrefs_count,
const char *language,
odocprovider__rad_dict_string_string_t **result,
odocprovider_Error_t **error);
Resolves given list of hrefs to a dictionary of either locally
or externally available targets.
Arguments:
inst -- RAD instance
hrefs -- List of URIs to be resolved.
hrefs_count -- Number of items in hrefs array
language (nullable) -- Language variant. If null it defaults to
en.
result -- Dictionary of all resolvable targets based on input
parameter hrefs.
Key is target href (same as in argument hrefs) and value is
either '-' for locally available targets (which can be
fetched just by key) or full URL in case of external
targets. If target is not resolvable, that key is not in
this dictionary list.
error
rc_err_t odocprovider_ODocProvider_getTargets(rc_instance_t *inst,
const char *topicGroup,
const char *navigationGroup,
const char *lang,
odocprovider_Target_t ***result,
int *result_cnt,
odocprovider_Error_t **error);
Retrieve all locally available Target structures in a tree-like
recursive form. Optionally list only targets that belong to the
specified topicGroup or navigationGroup group.
Arguments:
inst -- RAD instance
topicGroup (nullable) -- Only retrieve Target structures that
belong to this topic group. If null results for all available
groups will be retrieved.
navigationGroup (nullable) -- Only retrieve Target structures
that belong to this navigation group. If null results for all
available groups will be retrieved.
lang (nullable) -- Language variant. If null it defaults to en.
result -- Recursive list of Target structs.
result_cnt -- Number of items in result array
error
rc_err_t odocprovider_ODocProvider_getTopicGroups(rc_instance_t *inst,
boolean_t *includeHidden,
const char *language,
odocprovider__rad_dict_string_string_t **result,
odocprovider_Error_t **error);
Retrieve the list of all topic groups that have at least one
document available locally.
Arguments:
inst -- RAD instance
includeHidden (nullable) -- Include special-purpose hidden
groups that would not otherwise be reported to client
applications. If null it defaults to false.
language (nullable) -- Language variant. If null it defaults to
en.
result -- Dictionary of available topic groups.
error
rc_err_t odocprovider_ODocProvider_search(rc_instance_t *inst,
const char *query,
int *limit,
const char *language,
odocprovider_SearchResult_t ***result,
int *result_cnt,
odocprovider_Error_t **error);
Search locally indexed document content.
Arguments:
inst -- RAD instance
query -- Plain text query string.
limit (nullable) -- Maximum number of results. If limit is
null, the default maximum number of results is 1.
language (nullable) -- Language variant. If null it defaults to
en.
result
result_cnt -- Number of items in result array
error
ODocProvider Retrieve
rc_err_t odocprovider_ODocProvider__rad_get_name(adr_name_t **result,
int n,
...);
Obtain RAD name of a ODocProvider object.
Arguments:
result -- RAD name
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
rc_err_t odocprovider_ODocProvider__rad_lookup(rc_conn_t *c,
boolean_t strict,
rc_instance_t **result,
int n,
...);
Lookup a ODocProvider instance.
Construct a RAD name for the interface based on the provided
key-value pairs and perform a lookup. If successful, instance
reference is returned in the result.
Arguments:
c -- RAD connection handle
strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning
result -- RAD instance
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
rc_err_t odocprovider_ODocProvider__rad_list(rc_conn_t *c,
boolean_t strict,
adr_pattern_scheme_t scheme,
adr_name_t ***result,
int *result_count,
int n,
...);
List RAD names of a available ODocProvider instances.
Returns an array and array size of matching object names.
Arguments:
c -- RAD connection handle
strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning
scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching
result -- Array of RAD names
result_count -- Number of names in result array
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
ENUMERATED TYPES
enum ErrorType -- Enumeration of error types.
typedef enum odocprovider_ErrorType {
OET_ERR_DOCUMENT_NOT_FOUND = 0,
OET_ERR_INVALID_HREF = 1,
OET_ERR_INVALID_LANG = 2,
OET_ERR_SEARCH_UNAVAILABLE = 3,
OET_ERR_UNABLE_ACCESS_FILES = 4,
} odocprovider_ErrorType_t;
OET_ERR_DOCUMENT_NOT_FOUND (0) -- Document not found.
OET_ERR_INVALID_HREF (1) -- One or more hrefs are not valid.
OET_ERR_INVALID_LANG (2) -- Language variant is not valid.
OET_ERR_SEARCH_UNAVAILABLE (3) -- Search service is not available
or index is broken.
OET_ERR_UNABLE_ACCESS_FILES (4) -- Unable to access requested
document files.
STRUCTURED TYPES
struct Error -- Error descriptor.
typedef struct odocprovider_Error odocprovider_Error_t;
struct odocprovider_Error {
odocprovider_ErrorType_t oe_errorType;
char *oe_message;
};
void odocprovider_Error_free(odocprovider_Error_t *in);
Fields:
oe_errorType
oe_message -- Detailed error message.
struct Document -- A container for retrieved document content, Target
data, and, optionally, resolved target URIs.
typedef struct odocprovider_Document odocprovider_Document_t;
struct odocprovider_Document {
char *od_content;
odocprovider_Target_t *od_target;
odocprovider__rad_dict_string_string_t *od_resolvedTargets;
};
void odocprovider_Document_free(odocprovider_Document_t *in);
Fields:
od_content -- Document content in HTML.
od_target -- Target data for document content.
od_resolvedTargets -- Dictionary list of all resolvable targets in
the document content.
Key is target href and value is either '-' for locally
available targets (which can be fetched just by key) or full
URL in case of external targets. Unresolvable target keys are
not present in dictionary.
struct Target -- Recursive linkable target descriptor.
typedef struct odocprovider_Target odocprovider_Target_t;
struct odocprovider_Target {
char *ot_href;
odocprovider_Target_t **ot_targets;
int ot_targets_count;
char *ot_topicGroup;
char *ot_title;
char *ot_navigationGroup;
char **ot_labels;
int ot_labels_count;
};
void odocprovider_Target_free(odocprovider_Target_t *in);
Fields:
ot_href -- Target locator string of the form:
bundleId:docId#[linkId].
ot_targets -- A list of nested target structures.
ot_targets_count
ot_topicGroup -- The topic group to which the target belongs.
ot_title -- Target title.
ot_navigationGroup -- The navigation group, if any, to which the
target belongs. This metadata helps client applications build
navigation panels, for example.
ot_labels -- The list of labels to which the target is attached, in
the form sort_mode:label. This metadata helps client applications
organize targets in different ways for navigation purposes.
ot_labels_count
struct SearchResult -- A search result descriptor.
typedef struct odocprovider_SearchResult
odocprovider_SearchResult_t;
struct odocprovider_SearchResult {
odocprovider_Target_t *osr_target;
double osr_score;
};
void odocprovider_SearchResult_free(odocprovider_SearchResult_t *in);
Fields:
osr_target -- Target data for a matched document.
osr_score -- Match score.
DICTIONARIES
Dictionary { string : string }
Dictionary with a key type of string and a value type of string.
typedef struct base_rad_dict odocprovider__rad_dict_string_string_t;
rc_err_t odocprovider__rad_dict_string_string_get(odocprovider__rad_dict_string_string_t *dict,
const char *key,
char **result);
Get the value for given key.
Arguments:
dict -- Dictionary
key -- Key value
result -- Value returned
rc_err_t odocprovider__rad_dict_string_string_put(odocprovider__rad_dict_string_string_t *dict,
const char *key,
const char *value,
char **result);
Put a key-value pair into the dictionary.
Returns a previous value stored with the same key if one exists.
Arguments:
dict -- Dictionary
key -- Key value
value -- Value written
result -- Original value for the key
rc_err_t odocprovider__rad_dict_string_string_contains(odocprovider__rad_dict_string_string_t *dict,
const char *key);
Check whether a key exists in the dictionary.
Returns RCE_OK when key exists, RCE_CLIENT_NOTFOUND otherwise.
Arguments:
dict -- Dictionary
key -- Key value
rc_err_t odocprovider__rad_dict_string_string_remove(odocprovider__rad_dict_string_string_t *dict,
const char *key,
char **result);
Remove key-value pair from the dictionary.
Returns RCE_OK when key was sucessfully removed,
RCE_CLIENT_NOTFOUND otherwise.
Arguments:
dict -- Dictionary
key -- Key value
result -- Original value for the key
rc_err_t odocprovider__rad_dict_string_string_keys(odocprovider__rad_dict_string_string_t *dict,
char ***result,
int *count);
Get list of keys from the dictionary.
Memory associated with the result array should be freed by the
user.
Arguments:
dict -- Dictionary
result -- Array of dictionary keys
count -- Number of items in result array
rc_err_t odocprovider__rad_dict_string_string_values(odocprovider__rad_dict_string_string_t *dict,
char ***result,
int *count);
Get list of values from the dictionary.
Memory associated with the result array should be freed by the
user.
Arguments:
dict -- Dictionary
result -- Array of dictionary values
count -- Number of items in result array
unsigned int odocprovider__rad_dict_string_string_size(odocprovider__rad_dict_string_string_t *dict);
Get number of key-value pairs in the dictionary.
Arguments:
dict -- Dictionary
odocprovider__rad_dict_string_string_t * odocprovider__rad_dict_string_string_create(const rc_instance_t *inst);
Create a new, empty dictionary.
Returns a pointer to the dictionary, or NULL on error.
Arguments:
inst -- RAD instance
void odocprovider__rad_dict_string_string_free(odocprovider__rad_dict_string_string_t *dict);
Destroy the dictionary and release the allocated memory.
Arguments:
dict -- Dictionary
rc_err_t odocprovider__rad_dict_string_string_map(odocprovider__rad_dict_string_string_t *dict,
rc_err_t(*func)(const char *, const char *, void *),
void *arg);
Invoke a function with each key-value pair in the dictionary.
Arguments:
dict -- Dictionary
func -- Function to invoke
The arguments are: key, value, user-data.
arg -- User data: custom parameter to invoke the function with
VERSION
1.0
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------------------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------------------------------------+
|Availability | system/management/rad/module/rad-odocprovider |
+--------------------+-----------------------------------------------+
|Interface Stability | Private |
+--------------------+-----------------------------------------------+
SEE ALSO
rad(8)
NOTES
1. Accessing Python documentation for this module:
$ pydoc rad.bindings.com.oracle.solaris.rad.odocprovider_1
Solaris 11.4 2017-02-01 ODOCPROVIDER-1(3rad)