#
# This is my declarative definition of a function
#

Function('iFail', 'AOM_ask_value_strings', '''\
Asks one or more values of a property. The property can be single-valued or multi-valued (i.e., array or list).

This function uses #PROP_ask_value_strings_msg if multi-valued and #PROP_ask_value_string_msg if single-valued.
To customize the behavior of this function, register a method against one of these messages.''',
    [('tag_t'      , 'object_tag', 'I'       , '< (I) Unique identifier (tag) of the object instance.'),
     ('const char*', 'prop_name' , 'I'       , '< (I) A property name of the object instance.'),
     ('int*'       , 'num'       , 'OC'      , '< (O) Number of values asked.'),
     ('char***'    , 'values'    , 'OL(num)F', '< (OF) num Actual values of the property. This must be a list or array \n'
                                               '       of constant chars. If the property is an array, the number of \n'
                                               '       values passed in must equal the size of the array.\n'
                                               '       Iterate through the output array and call MEM_free on each element to de-allocate\n'
                                               '       the nested memory block and then free the memory pointed by itself using MEM_free.'),
    ]),



#
# This is automatically created in a .pxd
#

    cdef int AOM_ask_value_strings(
        # Asks one or more values of a property. The property can be single-valued or multi-valued (i.e., array or list).
        # 
        # This function uses #PROP_ask_value_strings_msg if multi-valued and #PROP_ask_value_string_msg if single-valued.
        # To customize the behavior of this function, register a method against one of these messages.
        tag_t   object_tag, # < (I) Unique identifier (tag) of the object instance.
        char*   prop_name , # < (I) A property name of the object instance.
        int*    num       , # < (O) Number of values asked.
        char*** values      # < (OF) num Actual values of the property. This must be a list or array 
                            #        of constant chars. If the property is an array, the number of 
                            #        values passed in must equal the size of the array.
                            #        Iterate through the output array and call MEM_free on each element to de-allocate
                            #        the nested memory block and then free the memory pointed by itself using MEM_free.
    )

#
# So is this in a .pyx
#
def AOM_ask_value_strings(tag_t object_tag, prop_name__py_str):
    '''
    Input:
      tag_t       object_tag (I) -- < (I) Unique identifier (tag) of the object instance.
      const char* prop_name  (I) -- < (I) A property name of the object instance.
    Output:
      char*** values (OL(num)F) -- < (OF) num Actual values of the property. This must be a list or array 
                                          of constant chars. If the property is an array, the number of 
                                          values passed in must equal the size of the array.
                                          Iterate through the output array and call MEM_free on each element to de-allocate
                                          the nested memory block and then free the memory pointed by itself using MEM_free.

    Asks one or more values of a property. The property can be single-valued or multi-valued (i.e., array or list).
    
    This function uses #PROP_ask_value_strings_msg if multi-valued and #PROP_ask_value_string_msg if single-valued.
    To customize the behavior of this function, register a method against one of these messages.
    '''
    cdef int __pytk__ifail__return__
    cdef char* prop_name
    cdef int num
    cdef char** values
    prop_name = PyString_AsString(prop_name__py_str) if prop_name__py_str != None else NULL
    if utils._nogil:
        with nogil:
            __pytk__ifail__return__ = ctccore__aom_prop.AOM_ask_value_strings(object_tag, prop_name, &num, &values)
    else:
        __pytk__ifail__return__ = ctccore__aom_prop.AOM_ask_value_strings(object_tag, prop_name, &num, &values)
    iFail2Exception(__pytk__ifail__return__)
    values__py_list = [str(values[pytk_i]) if values[pytk_i] != NULL else None for pytk_i in xrange(num)]
    for pytk_i in xrange(num):
        MEM_free(values[pytk_i])
    MEM_free(values)
    return values__py_list