14 Oracle Key Vault Client SDK TTLV Object APIs
The SDK TTLV
object APIs enable you to perform activities
such as getting the child of an OKVTTLV
object.
- About the Oracle Key Vault Client SDK TTLV Object APIs
Oracle Key Vault provides interfaces for the Oracle Key Vault KMIP parser and builder, which help build the OKVTTLV objects and help parse them. - okvTTLVAddToObject
okvTTLVAddToObject
creates an OKVTTLV object and makes this object a child object of the OKVTTLV parent object. - okvTTLVAddToObjectByTag
okvTTLVAddToObjectByTag
creates an OKVTTLV object and makes this object a child object of the OKVTTLV parent object. - okvTTLVGetChild
okvTTLVGetChild
retrieves a child OKVTTLV object from the OKVTTLV object at the given element index. - okvTTLVGetChildByTag
okvTTLVGetChildByTag
retrieves a child OKVTTLV object from the OKVTTLV object with the specified tag. - okvTTLVGetChildCount
okvTTLVGetChildCount
returns the number of child OKVTTLV objects of the specified OKVTTLV parent object. - okvTTLVGetChildCountByTag
okvTTLVGetChildCountByTag
will return the number of child OKVTTLV objects of the specified OKVTTLV parent object that have the given tag. - okvTTLVGetFirstChildByTag
okvTTLVGetFirstChildByTag
retrieves the first child of the OKVTTLV object that has the specified tag. - okvTTLVGetLen
okvTTLVGetLen
returns the length of the value of the OKVTTLV object. - okvTTLVGetRequest
okvTTLVGetRequest
returns the OKVTTLV request object of the operation. - okvTTLVGetResponse
okvTTLVGetResponse
returns the OKVTTLV response object of the custom KMIP operation. - okvTTLVGetTag
okvTTLVGetTag
returns the tag value of the OKVTTLV object. - okvTTLVGetType
okvTTLVGetType
returns the type value of the OKVTTLV object. - okvTTLVGetValue
okvTTLVGetValue
returns the pointer to the value of the OKVTTLV object. - okvTTLVGetValueCopy
okvTTLVGetValueCopy
copies the value of the OKVTTLV object into the supplied buffer.
Parent topic: Oracle Key Vault Client C SDK API Reference
14.1 About the Oracle Key Vault Client SDK TTLV Object APIs
Oracle Key Vault provides interfaces for the Oracle Key Vault KMIP parser and builder, which help build the OKVTTLV objects and help parse them.
TTLV stands for tag type length value. The element and attribute indexes used in the Oracle Key Vault SDK TTLV object APIs have same meaning as the Oracle Key Vault KMIP attribute APIs.
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.2 okvTTLVAddToObject
okvTTLVAddToObject
creates an OKVTTLV object and makes this
object a child object of the OKVTTLV parent
object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVAddToObject
will create an OKVTTLV object and make the newly
created OKVTTLV object a child object of the
OKVTTLV parent object.
Syntax
OKVTTLV *okvTTLVAddToObject(OKVEnv *env, OKVTTLV *ttlv, OKVTag tag, OKVType typ, void *val, ub4 len);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
ttlv |
IN |
OKVTTLV parent object. |
tag |
IN |
Tag of the OKVTTLV object. |
typ |
IN |
Type of the OKVTTLV object. |
val |
IN |
Value of the OKVTTLV object. |
len |
IN |
Length of value of the OKVTTLV object. |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
OKVTTLV object. Success: A valid pointer to the created OKVTTLV object is returned. Failure: A |
Comments
None.
Example
OKVTTLV *req = (OKVTTLV *) NULL; OKVTTLV *template; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); req = okvTTLVGetRequest(env, ops); ... template = okvTTLVAddToObject(env, req, OKVDEF_TAG_TEMPLATE_ATTR_ST, OKVDEF_ITEM_TYPE_STRUCT, (void *) NULL, (ub4) 0);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.3 okvTTLVAddToObjectByTag
okvTTLVAddToObjectByTag
creates an OKVTTLV object and makes
this object a child object of the OKVTTLV parent object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVAddToObjectByTag
will create an OKVTTLV object and make the
newly created OKVTTLV object a child object of the OKVTTLV parent
object.
Syntax
OKVTTLV *okvTTLVAddToObjectByTag(OKVEnv *env, OKVTTLV *ttlv, OKVTag tag, void *val, ub4 len);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle |
ttlv |
IN |
OKVTTLV parent object |
tag |
IN |
Tag of the OKVTTLV object |
val |
IN |
Value of the OKVTTLV object |
len |
IN |
Length of the value of the OKVTTLV object |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
OKVTTLV object Success: A valid pointer to the created OKVTTLV object is returned. Failure: A |
Comments
The difference between okvTTLVAddToObjectByTag
and
okvTTLVAddToObject
is that okvTTLVAddToObjectByTag
will try
to interpret the type from the tag. This can be done most of the times but not always.
Example
OKVTTLV *req = (OKVTTLV *) NULL; OKVTTLV *template; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); req = okvTTLVGetRequest(env, ops); ... template = okvTTLVAddToObjectByTag(env, req, OKVDEF_TAG_TEMPLATE_ATTR_ST, (void *) NULL, (ub4) 0);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.4 okvTTLVGetChild
okvTTLVGetChild
retrieves a child OKVTTLV object from the
OKVTTLV object at the given element
index.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetChild
retrieves a child OKVTTLV object from the OKVTTLV
object at the given element index. The tag and
type of the OKVTTLV object and length of the value
of the OKVTTLV object are also returned.
Syntax
OKVTTLV *okvTTLVGetChild(OKVEnv *env, OKVTTLV *ttlv, ub4 elem_index, OKVTag *tag, OKVType *typ, ub4 *len);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle |
ttlv |
IN |
OKVTTLV parent object |
elem_index |
IN |
Element index of the child OKVTTLV object |
tag |
OUT |
Tag of the child OKVTTLV object being retrieved |
typ |
OUT |
Type of the OKVTTLV object being retrieved |
len |
OUT |
Length of the value of the OKVTTLV object |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
Child OKVTTLV object at element index Success: A valid pointer to the child OKVTTLV object at element index
Failure: A NULL pointer is |
Comments
-
If
elem_index
exceeds the number of children, thenNULL
is returned. -
The tag of the value of OKVTTLV object is also returned if
tag
is notNULL
. -
The type of the value of OKVTTLV object is also returned if
typ
is notNULL
. -
The length of the value of OKVTTLV object is also returned if
len
is notNULL
.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; OKVTag ctag; OKVType ctyp; ub4 clen; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetChild(env, resp, 1, &ctag, &ctyp, &clen);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.5 okvTTLVGetChildByTag
okvTTLVGetChildByTag
retrieves a child OKVTTLV object from
the OKVTTLV object with the specified tag.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetChildByTag
is used to retrieve a child OKVTTLV object from
the OKVTTLV object with the specified tag at or after element index
elem_index
. The actual element index is also
returned.
Syntax
OKVTTLV *okvTTLVGetChildByTag(OKVEnv *env, OKVTTLV *ttlv, OKVTag tag, ub4 *elem_index);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
ttlv |
IN |
OKVTTLV parent object. |
tag |
IN |
Tag of the OKVTTLV object being retrieved. |
elem_index |
IN/OUT |
Element index of the child OKVTTLV object. |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
OKVTTLV object with the given tag. Success: A valid pointer to the child OKVTTLV object with the given tag at or
after element index Failure: A |
Comments
If elem_index
exceeds the number of children, then NULL
is returned.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; OKVTag ctag; OKVType ctyp; ub4 clen; ub4 elem_index = 0; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetChildByTag(env, resp, OKVDEF_TAG_ID, &elem_index); ctag = okvTTLVGetTag(tagid); ctyp = okvTTLVGetType(tagid); clen = okvTTLVGetLen(tagid);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.6 okvTTLVGetChildCount
okvTTLVGetChildCount
returns the number of child OKVTTLV
objects of the specified OKVTTLV parent object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVVGetChildCount
will return the number of child OKVTTLV
objects of the specified OKVTTLV parent object.
Syntax
ub4 okvTTLVGetChildCount(OKVTTLV *ttlv);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
Return Values
Return Value | Description |
---|---|
ub4 |
Number of child OKVTTLV objects of the specified OKVTTLV object. Success: Count of child OKVTTLV objects of the specified OKVTTLV parent object. Failure: A zero is returned on error or if the OKVTTLV parent object is not a
|
Comments
If the specified OKVTTLV object is not a STRUCTURE
, then zero is
returned. If the specified OKVTTLV object is a
STRUCTURE
and there was an error, zero is
returned.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; ub4 child_count; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); child_count = okvTTLVGetChildCount(resp);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.7 okvTTLVGetChildCountByTag
okvTTLVGetChildCountByTag
will return the number of child
OKVTTLV objects of the specified OKVTTLV parent object that have the given tag.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetChildCountByTag
will return the number of child OKVTTLV
objects of the specified OKVTTLV parent object that have the given
tag.
Syntax
ub4 okvTTLVGetChildCountByTag(OKVTTLV *ttlv, OKVTag tag);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
tag |
IN |
Tag of the child OKVTTLV objects being counted |
Return Values
Return Value | Description |
---|---|
ub4 |
Number of child OKVTTLV Objects of the specified OKVTTLV parent object with the given tag. Success: Count of the child OKVTTLV objects of the specified OKVTTLV parent object with the given tag. Failure: A zero is returned on error or if the OKVTTLV parent object is not a
|
Comments
If the specified OKVTTLV object is not a STRUCTURE
, then zero is
returned. If the specified OKVTTLV object is a
STRUCTURE
and there was an error, zero is
returned.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; ub4 unique_id_count; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); unique_id_count = okvTTLVGetChildCountByTag(resp, OKVDEF_TAG_ID);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.8 okvTTLVGetFirstChildByTag
okvTTLVGetFirstChildByTag
retrieves the first child of the
OKVTTLV object that has the specified tag.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetFirstChildByTag
is used to retrieve the first child of the
OKVTTLV object that has the specified tag.
Syntax
OKVTTLV *okvTTLVGetFirstChildByTag(OKVEnv *env, OKVTTLV *ttlv, OKVTag tag);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle |
ttlv |
IN |
OKVTTLV parent object |
tag |
IN |
Tag of the OKVTTLV object being retrieved |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
OKVTTLV object with the given tag. Success: A valid pointer to the child OKVTTLV object with the given tag is returned. Failure: A |
Comments
None.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; OKVTag ctag; OKVType ctyp; ub4 clen; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID); ctag = okvTTLVGetTag(tagid); ctyp = okvTTLVGetType(tagid); clen = okvTTLVGetLen(tagid);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.9 okvTTLVGetLen
okvTTLVGetLen
returns the length of the value of the OKVTTLV
object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetLen
will return the length of the value of the OKVTTLV
object.
Syntax
ub4 okvTTLVGetLen(OKVTTLV *ttlv);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
Return Values
Return Value | Description |
---|---|
ub4 |
Length of the OKVTTLV object value Success: Length of the value of the OKVTTLV object is returned. Failure: A zero is returned if the OKVTTLV object is a
|
Comments
If length returned is zero, then it implies an error except when the OKVTTLV type is
a STRUCTURE
.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; ub4 clen; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID); clen = okvTTLVGetLen(tagid);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.10 okvTTLVGetRequest
okvTTLVGetRequest
returns the OKVTTLV request object of the
operation.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetRequest
will return the OKVTTLV request object of the
operation. This object will be the root OKVTTLV object used to build
the KMIP Request. All OKVTTLV objects used in the KMIP request will
fall under the OKVTTLV request object.
Syntax
OKVTTLV *okvTTLVGetRequest(OKVEnv *env, OKVOps *ops);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle |
ops |
IN |
Oracle Key Vault operation handle |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
OKVTTLV request object for the operation. Success: A valid pointer to the OKVTTLV request object is returned. Failure: A |
Comments
None.
Example
OKVTTLV *req = (OKVTTLV *) NULL; OKVTTLV *attr_in = (OKVTTLV *)NULL; ... OKVOps *op = okvOpsCreate(env, OKVOpAddAttribute); req = okvTTLVGetRequest(env, op); attr_in = okvAddAttributeObject(env, req, OKVAttrName, 0); okvAttrAddName(env, attr_in, "XYZ", strlen("XYZ"), 1); okvAddAttribute(env, uid, &attr_in);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.11 okvTTLVGetResponse
okvTTLVGetResponse
returns the OKVTTLV response object of
the custom KMIP operation.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetResponse
will return the OKVTTLV response object of the
custom KMIP operation. This object will be used to parse the KMIP response from the
Oracle Key Vault server. All OKVTTLV objects of the KMIP response have to be
extracted and processed from the OKVTTLV response object.
Syntax
OKVTTLV *okvTTLVGetResponse(OKVEnv *env, OKVOps *ops);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
IN |
Oracle Key Vault environment handle. |
ops |
IN |
Oracle Key Vault operation handle. |
Return Values
Return Value | Description |
---|---|
OKVTTLV* |
OKVTTLV response object of the operation. Success: A valid pointer to the OKVTTLV Response object is returned. Failure: A |
Comments
None.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; OKVTag ctag, rtag; OKVType ctyp, rtyp; oratext cval[OKV_UNIQUE_ID_MAXLEN + 1], rval[OKV_UNIQUE_ID_MAXLEN + 1]; ub4 clen, rlen; OKVOps *ops[2]; ... /* Get the result of the First Batch Operation */ ops[0] = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops[0]); /* Retrieve the Unique Identifier */ tagid = okvTTLVGetChild(env, resp, 1, &ctag, &ctyp, &clen); printf("\n%d %d %d ", ctag, ctyp, clen); okvTTLVGetValueCopy(tagid, (void *)cval, clen); cval[clen] = 0; printf("%s\n", cval); /* Print the Unique Identifier */ /* Get the result of the Second Batch Operation */ ops[1] = okvOpsCreate(env, OKVOpActivate); resp = okvTTLVGetResponse(env, ops[1]); /* Retrieve the Unique Identifier */ tagid = okvTTLVGetChild(env, resp, 0, &rtag, &rtyp, &rlen); printf("\n%d %d %d ", rtag, rtyp, rlen); okvTTLVGetValueCopy(tagid, (void *)rval, rlen); rval[rlen] = 0; printf("%s\n", rval); /* Print the Unique Identifier */
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.12 okvTTLVGetTag
okvTTLVGetTag
returns the tag value of the OKVTTLV object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetTag
will return the tag value of the OKVTTLV object.
Syntax
OKVTag okvTTLVGetTag(OKVTTLV *ttlv);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
Return Values
Return Value | Description |
---|---|
OKVTag |
Tag of the OKVTTLV object. Success: A valid tag value of the OKVTTLV object is returned. Failure: A zero is returned. |
Comments
None.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; OKVTag ctag; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID); ctag = okvTTLVGetTag(tagid);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.13 okvTTLVGetType
okvTTLVGetType
returns the type value of the OKVTTLV object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetType
will return the type value of the OKVTTLV object.
Syntax
OKVType okvTTLVGetType(OKVTTLV *ttlv);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
Return Values
Return Value | Description |
---|---|
OKVType |
Type of the OKVTTLV object. Success: A valid Type value of the OKVTTLV object is returned. Failure: A zero is returned if there was an error. |
Comments
None.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; OKVType ctyp; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID); ctyp = okvTTLVGetType(tagid);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.14 okvTTLVGetValue
okvTTLVGetValue
returns the pointer to the value of the
OKVTTLV object.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetValue
returns the pointer to the value of the OKVTTLV
object.
Syntax
void *okvTTLVGetValue(OKVTTLV *ttlv);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
Return Values
Return Value | Description |
---|---|
void* |
OKVTTLV object value. Success: Pointer to the value of the OKVTTLV object is returned. Failure: A NULL pointer is returned if there is an error. |
Comments
None.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; ub4 clen; oratext *cval; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID); clen = okvTTLVGetLen(tagid); cval = (oratext *) okvTTLVGetValue(tagid); cval[clen] = 0; printf("%s", cval);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs
14.15 okvTTLVGetValueCopy
okvTTLVGetValueCopy
copies the value of the OKVTTLV object
into the supplied buffer.
Category
KMIP extension TTLV object API
Purpose
okvTTLVGetValueCopy
will copy the value of the OKVTTLV object into
the supplied buffer.
Syntax
ub4 okvTTLVGetValueCopy(OKVTTLV *ttlv, void *val, ub4 len);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
ttlv |
IN |
OKVTTLV object |
val |
OUT |
Buffer for the OKVTTLV object value |
len |
IN |
Length of the OKVTTLV object value |
Return Values
Return Value | Description |
---|---|
ub4 |
Length of the OKVTTLV object value. Success: Length of the value of the OKVTTLV object is returned. Failure: Zero is returned. |
Comments
The memory for the value has to be pre-allocated before making a call to this function.
Depending on the type of the OKVTTLV object, the value can be interpreted
differently. For example, if the type of the OKVTTLV object is
INTEGER
, then the value can be stored in a ub4 variable.
However, if the OKVTTLV object is a BYTE STRING
, the value is a ub1
array of length len
.
This function should not be used for OKVTTLV objects that are of type
STRUCTURE
.
Example
OKVTTLV *resp = (OKVTTLV *) NULL; OKVTTLV *tagid = (OKVTTLV *) NULL; ub4 clen; oratext cval[OKV_UNIQUE_ID_MAXLEN + 1]; ... OKVOps *ops = okvOpsCreate(env, OKVOpCreate); resp = okvTTLVGetResponse(env, ops); tagid = okvTTLVGetFirstChildByTag(env, resp, OKVDEF_TAG_ID); clen = okvTTLVGetLen(tagid); okvTTLVGetValueCopy(tagid, (void *)cval, clen); cval[clen] = 0; printf("%s", cval);
Related Topics
Parent topic: Oracle Key Vault Client SDK TTLV Object APIs