Binary data type represents binary data, for example, sequence of octets. A binary type can be restricted with the "length" statement. The length of a binary value is the number of octets it contains.
Binary values should be encoded with the base64 encoding scheme.
The internal representation for the binary data type is a binary buffer. It is NOT a zero-terminated printable string. The base64 encoding used within NETCONF messages is printable but not the raw binary string that is accessible within the server SIL code. All examples below show the source string as a printable string but in fact this could be a real binary string (e.g., contents of a JPG file)
Consider the following YANG module example:
module example {
namespace "http://yumaworks.com/ns/example";
prefix "example";
revision 2019-07-30 {
description
"Initial example module for binary type";
}
leaf yang-binary-example {
type binary {
length '6';
}
default "SGVsbG8h"; // base64 value of "Hello!"
}
}Note that the default value for the binary node must be encoded in base64.
This leaf can be accessed using several ways described below
1) Using RESTCONF request:
To create a new "yang-binary-example" node using RESTCONF client, the client might send the following POST request:
POST /restconf/data/ HTTP/1.1
Host: example-server
Content-Type: application/yang-data+json
{
"yang-binary-example":"eWVsbG93"
}Note that the value for this node is base64 encoded.
If the resource is created, the server might respond as follows:
HTTP/1.1 201 Created
Server: example-server
Location: https://example-server/restconf/data/yang-binary-exampleIf the POST method succeeds, a "201 Created" Status is returned and there is no response message-body. A "Location" header field identifying the resource node that was created. If the data resource already exists, then the POST request will fail and a "409 Conflict" status-line will be returned.
To retrieve just created node, the GET method can be sent by the client as follows:
GET /restconf/data/yang-binary-type HTTP/1.1
Host: example-server
Accept: application/yang-data+xmlThe server might respond as follows:
HTTP/1.1 200 OK
Server: example-server
Content-Type: application/yang-data+xml
<yang-binary-example xmlns="http://yumaworks.com/ns/example">eWVsbG93</yang-binary-example>2) Using yangcli-pro:
To create a new "yang-binary-example" node using yangcli-pro client, the client might send the following POST request:
user@server> create /yang-binary-example value=yellow user@server> commit
Yangcli-pro expects a raw string and will encode the given value to base64. So, there is no need to encode the value prior. If the value to be assigned is encoded, yangcli-pro will encode it again, that will result double encoded value to be used.
Also, the length restriction will apply to value entered by the user. If the length of a given value does not match with the restricted length, the server will reply with rpc-error "value not in range".
To retrieve just created binary leaf, the following request might be sent:
user@server> sget /yang-binary-example
The server might respond with rpc-reply, containing below information:
<rpc-reply> <data> <yang-binary-example xmlns="http://yumaworks.com/ns/example">eWVsbG93</yang-binary-example> </data> </rpc-reply>
If the value of a binary node is set by providing JSON file (inline or by using @file.json), the value must be base64 encoded. The following example illustrates how the binary leaf can be set by using inline JSON file:
edit-config target=candidate config="""
{"config": {
"yang-binary-example" : "eWVsbG93"
}
}
"""If the value of a binary node is set by providing XML file (inline or by using @file.xml), the value must be base64 encoded. The following example illustrates how the binary leaf can be set by using inline XML file:
edit-config target=candidate config=""" <config> <yang-binary-example>eWVsbG93</yang-binary-example> </config> """
To retrieve just created binary leaf, the following request might be sent:
user@server> sget /yang-binary-example
The server might respond with rpc-reply, containing below information:
<rpc-reply> <data> <yang-binary-example xmlns="http://yumaworks.com/ns/example">eWVsbG93</yang-binary-example> </data> </rpc-reply>
Yangcli-pro, however, will output this message as follows. It does so to ensure integrity of the string values, since the binary values may contain characters that yangcli-pro cannot use in the logging.
rpc-reply {
data {
yang-binary-example binary string, length '6'
}
}3) Using DB-API:
In order to create a binary value by using DB-API the value should be encoded in base64. The following example illustrates how to set binary leaf value.
/********************************************************************
* FUNCTION send_test_edit
*
* This is an example send edit function for binary node.
*
*********************************************************************/
static void
send_test_edit (void)
{
const xmlChar *path_str = (const xmlChar *)"/";
const xmlChar *operation_str = (const xmlChar *)"merge";
const xmlChar *value_str = (const xmlChar *)
"<config>"
"<yang-binary-example xmlns='http://yumaworks.com/ns/example'>eWVsbG93</yang-binary-example>"
"</config>";
const xmlChar *patch_id_str = NULL;
boolean system_edit = FALSE;
status_t res = db_api_send_edit_ex(path_str,
operation_str,
value_str,
patch_id_str,
system_edit);
if (res != NO_ERR) {
log_error("\nSend test edit for binary node failed %s %s = %s (%s)\n",
operation_str, path_str, value_str,
get_error_string(res));
} else if (LOGDEBUG) {
log_debug("\nSend test edit for binary node OK %s %s = %s\n",
operation_str, path_str, value_str);
}
} /* send_test_edit */BINARY leaf and SIL code:
Binary data type is treated similar to the string type, except it needs to be decoded to proceed further.
The following APIs and Macros can be used with the binary type val value node. Refer to val.h:
- val_make_binary_obj(): Function that malloc a new binary val value node, it will be picked automatically based on the object type.
- val_make_simval_obj(): Function that malloc a new val value node and does not need to know the type, it will be picked automatically based on the provided object type.
- VAL_BINARY(v): binary string.
- VAL_BINARY_LEN(v): binary length.
Consider following YANG module:
...
leaf yang-binary-example-1 {
config false;
type binary;
}
leaf yang-binary-example-2 {
config false;
type binary;
}
...Following code example creates the value of binary node and outputs it to the standard log output using val_make_simval_obj().
This is just an example of how the following API can be used:
...
/* create a binary leaf val value node */
val_value_t *return_val =
val_make_simval_obj(obj,
(const xmlChar *)"yellow",
&res);
if (return_val) {
/* Output the value to the standard output log */
log_info("\nCreated binary node; length:'%u'",
VAL_BINARY_LEN(return_val));
}
...The server might output the following logging information to the standard output:
... Created binary node; value:'eWVsbG93' length:'6' ...
Following code example will create the binary node and output it to the standard output using val_make_binary_obj().
...
/* create a new binary type node */
val_value_t *return_val =
val_make_binary_obj(obj,
(const xmlChar *)"yellow",
(uint32)6,
&res);
if (return_val) {
/* Output the value to the standard output log */
log_info("\nCreated binary node; value:'%s' length:'%u'",
VAL_BINARY(return_val),
VAL_BINARY_LEN(return_val));
}
...The server might output the following logging information to the standard output:
... Created binary node; length:'6' ...