[#104] add a setbuf method for BytesBuf structure.

Also allow freeing bytesBuf heap pointer when the Python object goes
out of scope.

Added borrowed ref in set_buffer; bounds checking in get_byte;
and overloaded function giving (in effect) a default of -1 for length.
(I.e. auto-sense the length of the passed object.)

Author: d-w-moore

README.md

@@ -190,6 +190,40 @@ def get_irods_username (rule_args, callback, rei):
   rule_args [0] = username
 ```
 
+## Special methods
+
+Some iRODS objects used with rules and microservices have been given utility methods.
+
+An example is the map() method of a `PluginContext` PEP argument:
+```
+    def pep_resource_resolve_hierarchy_pre(rule_args, callback, rei):
+        import pprint
+        pprint.pprint(rule_args[1].map().items())
+```
+
+In version 4.2.11.2 of the Python plugin, `BytesBuf` has methods to set and access byte content.
+These can be used to achieve true binary reads and writes, to and from data objects.
+
+For example:
+```
+    def my_rule(args, callback, rei):
+        buf = irods_types.BytesBuf()
+        buf.set_buffer( os.urandom(256) )
+        callback.msiDataObjectWrite( descriptor, buf, 0)  #-- Write the buffer.
+        # ...
+        buf.clear_buffer()
+```
+or:
+```
+    # ...
+    retv = callback.msiDataObjectRead( descriptor, "256", irods_types.BytesBuf())
+    returnbuf = retv['arguments'][2]
+    out = returnbuf.get_bytes()         #--  Returns list of integer octets.
+    start_byte = returnbuf.get_byte(0)  #--  Returns first octet
+```
+
+
+
 ## `genquery.py`
 
 This module offers writers of Python rules a convenient facility for querying and iterating over objects in the iRODS object catalog (ICAT).

irods_types.cpp

@@ -31,6 +31,26 @@ bool operator==(const sqlResult_t& s1, const sqlResult_t& s2) {
 }
 
 namespace {
+
+    void set_buffer_2argument_form_(bytesBuf_t* self, PyObject *c, int L)
+    {
+	bp::handle<> handle{bp::borrowed(c)}; // The PyObject*c will be "borrowed" in the context of this function, meaning
+	bp::object obj {handle};              // we increment its reference count until the handle goes out of scope.
+	if (L < 0) {
+	    L = bp::len(obj);
+	}
+	self->buf = realloc(self->buf, L);
+	if (self->buf) {
+	    self->len = L;
+	    auto *buf_dest = reinterpret_cast<unsigned char *>(self->buf);
+	    for (int i=0; i<L; i++) {
+		*buf_dest++ = bp::extract<unsigned char>{ obj[i] };
+	    }
+	}
+    }
+
+    void set_buffer( bytesBuf_t* self, PyObject *c) { set_buffer_2argument_form_(self,c,-1); }
+
     BOOST_PYTHON_MODULE(irods_errors)
     {
 	    std::map <std::string, int> irods_constants;
@@ -1007,6 +1027,27 @@ namespace {
             .def("__init__", make_init_function<bytesBuf_t>(
                         &bytesBuf_t::len,
                         &bytesBuf_t::buf))
+            .def("get_byte", +[]( bytesBuf_t* s, std::size_t n)->unsigned char {
+                                      if (n >= s->len) {
+                                          PyErr_SetString(PyExc_IndexError, "BytesBuf out-of-range access");
+                                          throw bp::error_already_set();
+                                      }
+                                      return static_cast<char*>(s->buf)[n];
+                                  })
+            .def("get_bytes", +[]( bytesBuf_t* s) {
+                                                      bp::object None;
+                                                      bp::list a{};
+                                                      a.append(None);   // construct a list of length 1 and expand it...
+                                                      a *= s->len;      // ... to the desired length.
+                                                      auto buf_src = static_cast<unsigned char*>(s->buf);
+                                                      for (int j=0; j<s->len; j++) {
+                                                          a[j]=*buf_src++;
+                                                      }
+                                                      return a;
+                                                  })
+            .def("clear_buffer", clearBBuf)
+            .def("set_buffer",set_buffer)
+            .def("set_buffer",set_buffer_2argument_form_)
             .add_property("len", &bytesBuf_t::len)
             .add_property("buf", +[](bytesBuf_t *s) { return s->buf ? bp::object{array_ref<char>{static_cast<char*>(s->buf), static_cast<std::size_t>(s->len)}} : bp::object{}; })
             ;

python_rules/rulemsiDataObjWrite_binary.r

@@ -0,0 +1,59 @@
+def main(rule_args, callback, rei):
+    return data_obj_binary_write_test__104(callback)
+
+class error_tracker:
+
+    def __init__(self):
+        self.code = 0
+
+    def assert_(self,
+                nonzero_value,
+                bool_lambda = lambda:False):   # The lambda is for lazy evaluation.
+                                               # `nonzero_value' should be negative and not be
+                                               # the same in absolute value as any valid errno code.
+        if self.code == 0:
+            self.code = (0 if bool_lambda() else nonzero_value)
+
+def data_obj_binary_write_test__104(callback):
+
+    binary_bytes = irods_types.BytesBuf()
+
+    buffer = bytearray((256 + 127 - i) % 256 for i in range(256))  # Create a list of [127,126,...,0,255,254,...,128]
+    buffer_length = len(buffer)
+    dest_file = '/tempZone/home/rods/test_buffer__104'
+
+    binary_bytes.set_buffer(buffer)
+
+    err = error_tracker()
+    try:
+        binary_bytes.get_byte(10240)
+    except IndexError:
+        pass               # This error is the expected result of get_byte with too large an index.
+    else:
+        err.assert_(-997)  # Error because an exception should have been thrown by the out-of-range access.
+
+    ret_val = callback.msiDataObjOpen(
+       ('objPath={}++++openFlags=O_RDWR''O_CREAT''O_TRUNC').format(dest_file)
+       , 0)
+    f = ret_val['arguments'][1]
+
+    callback.msiDataObjWrite(f, binary_bytes, buffer_length)
+    binary_bytes.clear_buffer()
+
+    callback.msiDataObjLseek(f, "0", "SEEK_SET", 0)
+
+    ret_val = callback.msiDataObjRead(f, str(16+buffer_length), irods_types.BytesBuf())
+    read_buffer = ret_val['arguments'][2]
+
+    err.assert_(-999, lambda: list(buffer) == read_buffer.get_bytes())
+    err.assert_(-998, lambda: buffer_length == read_buffer.len)
+
+    read_buffer.clear_buffer()
+
+    callback.msiDataObjClose(f, 0)
+    callback.msiDataObjUnlink("objPath="+dest_file,0)
+
+    return err.code
+
+INPUT null
+OUTPUT ruleExecOut