Max 5 API Reference

pattr-api-doxygen.c

<?xml version="1.0" encoding="UTF-8"?>

<category>
<cattitle>Class Functions</cattitle>

// function: class_new
/**
 * Initializes a class by informing Max of its name, instance creation and free functions, size and argument types.  Developers wishing to use obex class features (attributes, etc.) <em>must</em>  use <tt>class_new</tt> instead of the traditional <tt>setup</tt> function.
 *
 * @param   name    The class's name, as a C-string
 * @param   mnew    The instance creation function
 * @param   mfree   The instance free function
 * @param   size    The size of the object's data structure in bytes. Usually 
 *                  you use the C sizeof operator here.
 * @param   mmenu   The function called when the user creates a new object of the  
 *                  class from the Patch window's palette (UI objects only).  
 *                  Pass 0L if you're not defining a UI object.
 * @param   type    A standard Max <em>type list</em> as explained in Chapter 3  
 *                  of the Writing Externals in Max document (in the Max SDK).  
 *                  The final argument of the type list should be a 0.  
 *                  <em>Generally, obex objects have a single type argument</em>,  
 *                  <tt>A_GIMME</tt>, followed by a 0.
 *
 * @return  This function returns the class pointer for the new object class. 
 *          <em>This pointer is used by numerous other functions and should be 
 *          stored in a global variable.</em>
 *
 */

// function: class_free
/**
 * Frees a previously defined object class. <em>This function is not typically used by external developers.</em>
 *
 * @param   c       The class pointer
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: class_register
/**
 * Registers a previously defined object class. This function is required, and should be called at the end of <tt>main()</tt>.
 *
 * @param   name_space  The desired class's name space. Typically, either the 
 *                      constant <tt>CLASS_BOX</tt>, for obex classes which can 
 *                      instantiate inside of a Max patcher (e.g. boxes, UI objects, 
 *                      etc.), or the constant <tt>CLASS_NOBOX</tt>, for classes 
 *                      which will only be used internally. Developers can define 
 *                      their own name spaces as well, but this functionality is 
 *                      currently undocumented.
 * @param   c           The class pointer
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: class_addmethod
/**
 * Adds a method to a previously defined object class. 
 *
 * @param   c       The class pointer
 * @param   m       Function to be called when the method is invoked
 * @param   name    C-string defining the message (message selector)
 * @param   ...     One or more integers specifying the arguments to the message, 
 *                  in the standard Max type list format (see Chapter 3 of the 
 *                  Writing Externals in Max document for more information).
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  The <tt>class_addmethod</tt> function works essentially like the 
 *          traditional <tt>addmess</tt> function, adding the function pointed to  
 *          by <tt>m</tt>, to respond to the message string <tt>name</tt> in the   
 *          leftmost inlet of the object. 
 *
 */

// function: class_addattr
/**
 * Adds an attribute to a previously defined object class. 
 *
 * @param   c       The class pointer
 * @param   attr    The attribute to add. The attribute will be a pointer returned 
 *                  by <tt>attribute_new</tt>, <tt>attr_offset_new</tt> or 
 *                  <tt>attr_offset_array_new</tt>.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: class_addadornment
/**
 * Adds an adornment to a previously defined object class. At this time, this function is non-functional and undocumented.
 *
 * @param   c       Undocumented
 * @param   o       Undocumented
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: class_obexoffset_set
/**
 * Registers the byte-offset of the obex member of the class's data structure with the previously defined object class. Use of this function is required for obex-class objects. It must be called from <tt>main()</tt>.
 *
 * @param   c       The class pointer
 * @param   offset  The byte-offset to the obex member of the object's data structure. 
 *                  Conventionally, the macro <tt>calcoffset</tt> is used to calculate the offset.
 *
 */

// function: class_obexoffset_get
/**
 * Retrieves the byte-offset of the obex member of the class's data structure.
 *
 * @param   c       The class pointer
 *
 * @return  This function returns the byte-offset of the obex member of the class's data structure.
 *
 */

// function: class_name_get
/**
 * Retrieves the name of a class, given the class's pointer.
 *
 * @param   c       The class pointer
 *
 * @return  If successful, this function returns the name of the class as a t_symbol *. 
 *
 */

// function: class_findbyname
/**
 * Finds the class pointer for a class, given the class's namespace and name.
 *
 * @param   name_space  The desired class's name space. Typically, either the 
 *                      constant <tt>CLASS_BOX</tt>, for obex classes which can 
 *                      instantiate inside of a Max patcher (e.g. boxes, UI objects, 
 *                      etc.), or the constant <tt>CLASS_NOBOX</tt>, for classes 
 *                      which will only be used internally. Developers can define 
 *                      their own name spaces as well, but this functionality is 
 *                      currently undocumented.
 * @param   classname   The name of the class to be looked up
 *
 * @return  If successful, this function returns the class's data pointer. Otherwise, it returns NULL.
 *
 */

// function: calcoffset
/**
 * The macro <tt>calcoffset</tt> is used as follows:
 *
 * @param   classtype   The class's defined type (e.g. <tt>t_myobject</tt>)
 * @param   varname     The name of a variable in the class's data structure.
 *
 * @return  The macro returns the byte-offset of the specified variable within 
 *          the class data structure for the specified class type.
 *
 */

</category>

<category>
<cattitle>Object Functions: instantiation and freeing</cattitle>

// function: object_alloc
/**
 * Allocates the memory for an instance of an object class and initialize its object header. It is used like the traditional function <tt>newobject</tt>, inside of an object's <tt>new</tt> method, but its use is required with obex-class objects.
 *
 * @param   c       The class pointer, returned by <tt>class_new</tt>
 *
 * @return  This function returns a new instance of an object class if successful, or NULL if unsuccessful.
 *
 */

// function: object_new
/**
 * Allocates the memory for an instance of an object class and initialize its object header <em>internal to Max</em>. It is used similarly to the traditional function <tt>newinstance</tt>, but its use is required with obex-class objects.
 *
 * @param   name_space  The desired object's name space. Typically, either the 
 *                      constant <tt>CLASS_BOX</tt>, for obex classes which can 
 *                      instantiate inside of a Max patcher (e.g. boxes, UI objects, 
 *                      etc.), or the constant <tt>CLASS_NOBOX</tt>, for classes 
 *                      which will only be used internally. Developers can define 
 *                      their own name spaces as well, but this functionality is 
 *                      currently undocumented.
 * @param   classname   The name of the class of the object to be created
 * @param   ...         Any arguments expected by the object class being instantiated
 *
 * @return  This function returns a new instance of the object class if successful, or NULL if unsuccessful.
 *
 */

// function: object_new_typed
/**
 * Allocates the memory for an instance of an object class and initialize its object header <em>internal to Max</em>. It is used similarly to the traditional function <tt>newinstance</tt>, but its use is required with obex-class objects. The <tt>object_new_typed</tt> function differs from <tt>object_new</tt> by its use of an atom list for object arguments—in this way, it more resembles the effect of typing something into an object box from the Max interface.
 *
 * @param   name_space  The desired object's name space. Typically, either the 
 *                      constant <tt>CLASS_BOX</tt>, for obex classes which can 
 *                      instantiate inside of a Max patcher (e.g. boxes, UI objects, 
 *                      etc.), or the constant <tt>CLASS_NOBOX</tt>, for classes 
 *                      which will only be used internally. Developers can define 
 *                      their own name spaces as well, but this functionality is 
 *                      currently undocumented.
 * @param   classname   The name of the class of the object to be created
 * @param   ac          Count of arguments in <tt>av</tt>
 * @param   av          Array of t_atoms; arguments to the class's instance creation function.
 *
 * @return  This function returns a new instance of the object class if successful, or NULL if unsuccessful.
 *
 */

// function: object_free
/**
 * Call the free function and release the memory for an instance of an internal object class previously instantiated using <tt>object_new</tt>, <tt>object_new_typed</tt> or other new-style object constructor functions (e.g. <tt>hashtab_new</tt>). It is, at the time of this writing, a wrapper for the traditional function <tt>freeobject</tt>, but its use is suggested with obex-class objects.
 *
 * @param   x       The pointer to the object to be freed. 
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

</category>

<category>
<cattitle>Object Functions: sending messages</cattitle>

// function: object_method
/**
 * Sends an untyped message to an object. 
 *
 * @param   x       The object that will receive the message 
 * @param   s       The message selector
 * @param   ...     Any arguments to the message
 *
 * @return  If the receiver object can respond to the message, <tt>object_method</tt> returns the result. Otherwise, the function will return 0. 
 *
 * @remark  Example: To send the message <tt>bang</tt> to the object <tt>bang_me</tt>:
@code
void *bang_result;
bang_result = object_method(bang_me, gensym("bang"));</proto>
@endcode
 *
 */

// function: object_method_typed
/**
 * Sends a type-checked message to an object. 
 *
 * @param   x       The object that will receive the message 
 * @param   s       The message selector
 * @param   ac      Count of message arguments in <tt>av</tt>
 * @param   av      Array of t_atoms; the message arguments
 * @param   rv      Return value of function, if available
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  If the receiver object can respond to the message, <tt>object_method_typed</tt> returns the result in <tt>rv</tt>. Otherwise, <tt>rv</tt> will contain an <tt>A_NOTHING</tt> atom.
 *
 */

// function: object_method_typedfun
/**
 * Currently undocumented. 
 *
 * @param   x       The object that will receive the message 
 * @param   mp      Undocumented
 * @param   s       The message selector
 * @param   ac      Count of message arguments in <tt>av</tt>
 * @param   av      Array of t_atoms; the message arguments
 * @param   rv      Return value of function, if available
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  If the receiver object can respond to the message, <tt>object_method_typedfun</tt> returns the result in <tt>rv</tt>. Otherwise, <tt>rv</tt> will contain an <tt>A_NOTHING</tt> atom.
 *
 */

// function: object_getmethod
/**
 * Retrieves an object's <tt>method</tt> for a particular message selector.
 *
 * @param   x       The object whose method is being queried
 * @param   s       The message selector
 *
 * @return  This function returns the <tt>method</tt> if successful, or 0 if unsuccessful.
 *
 */

</category>

<category>
<cattitle>Object Functions: obex</cattitle>

// function: object_obex_store
/**
 * Stores data in the object's obex. 
 *
 * @param   x       The object pointer. This function should only be called on instantiated objects (i.e. in the <tt>new</tt> method or later), not directly on classes (i.e. in <tt>main()</tt>).
 * @param   key     A symbolic name for the data to be stored
 * @param   val     A <tt>t_object *</tt>, to be stored in the obex, referenced under the <tt>key</tt>.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  Most developers will need to use this function for the specific purpose of storing the dumpout outlet in the obex (the dumpout outlet is used by attributes to report data in response to 'get' queries). For this, the developer should use something like the following in the object's <tt>new</tt> method:
@code
object_obex_store(x, _sym_dumpout, outlet_new(x, NULL));
@endcode
 *
 */

// function: object_obex_lookup
/**
 * Retrieves the value of a data stored in the obex. 
 *
 * @param   x       The object pointer. This function should only be called on instantiated objects (i.e. in the <tt>new</tt> method or later), not directly on classes (i.e. in <tt>main()</tt>).
 * @param   key     The symbolic name for the data to be retrieved
 * @param   val     A pointer to a <tt>t_object *</tt>, to be filled with the data retrieved from the obex.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  By default, pointers to the object's containing t_patcher and t_box objects are stored in the obex, under the keys '#P' and '#B', respectively. To retrieve them, the developer could do something like the following:
@code
void post_containers(t_obexobj *x)
{
    t_patcher *p;
    t_box *b;

    p = object_obex_lookup(x, gensym("#P"), (t_object **)&p);
    b = object_obex_lookup(x, gensym("#B"), (t_object **)&b);

    post("my patcher is located at 0x%X", p);
    post("my box is located at 0x%X", b);
}
@endcode
 *
 */

// function: object_obex_dumpout
/**
 * Sends data from the object's dumpout outlet. The dumpout outlet is stored in the obex using the <tt>object_obex_store</tt> function (see above) It is used approximately like <tt>outlet_anything</tt>.
 *
 * @param   x       The object pointer. This function should only be called on instantiated objects (i.e. in the <tt>new</tt> method or later), not directly on classes (i.e. in <tt>main()</tt>).
 * @param   s       The message selector t_symbol *
 * @param   argc    Number of elements in the argument list in argv
 * @param   argv    t_atoms constituting the message arguments
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_obex_set
/**
 * Currently undocumented.
 *
 * @param   x       <em>undocumented</em>
 * @param   obex    <em>undocumented</em>
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_obex_get
/**
 * Currently undocumented.
 *
 * @param   x       <em>undocumented</em>
 *
 * @return  The return value is undocumented.
 *
 */

</category>

<category>
<cattitle>Object Functions: miscellaneous</cattitle>

// function: object_classname_compare
/**
 * Determines if a particular object is an instance of a given class.
 *
 * @param   x       The object to test
 * @param   name    The name of the class to test the object against
 *
 * @return  This function returns 1 if the object is an instance of the named class. Otherwise, 0 is returned.
 *
 * @remark  For instance, to determine whether an unknown object pointer is a pointer to a print object, you'd call:
@code
long isprint = object_classname_compare(x, gensym("print"));
@endcode
 *
 */

// function: object_class
/**
 * Determines the class of a given object.
 *
 * @param   x       The object to test
 *
 * @return  This function returns the t_class * of the object's class, if successful, or <tt>NULL</tt>, if unsuccessful.
 *
 */

// function: object_getvalueof
/**
 * Retrieves the value of an object which supports the <tt>getvalueof/setvalueof</tt> interface. See part 2 of the pattr SDK for more information on this interface.
 *
 * @param   x       The object whose value is of interest
 * @param   ac      Pointer to a long variable to receive the count of arguments in <tt>av</tt>. The long variable itself should be set to 0 previous to calling this function.
 * @param   av      Pointer to a t_atom *, to receive object data. The t_atom * itself should be set to <tt>NULL</tt> previous to calling this function.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  Calling the <tt>object_getvalueof</tt> function allocates memory for any data it returns. It is the developer's responsibility to free it, using the <tt>freebytes</tt> function.
 *
 * @remark  Developers wishing to design objects which will support this function being called on them must define and implement a special method, <tt>getvalueof</tt>, like so:
@code
class_addmethod(c, (method)myobject_getvalueof, "getvalueof", A_CANT, 0);
@endcode
 *
 * @remark  The <tt>getvalueof</tt> method should be prototyped as:
@code
t_max_err myobject_getvalueof(t_myobject *x, long *ac, t_atom **av);
@endcode
 *
 * @remark  And implemented, generally, as:
@code
t_max_err myobj_getvalueof(t_myobj *x, long *ac, t_atom **av) 
{
    if (ac && av) {
        if (*ac && *av) {
            // memory has been passed in; use it.
        } else {
            // allocate enough memory for your data
            *av = (t_atom *)getbytes(sizeof(t_atom));
        }
        *ac = 1; // our data is a single floating point value
        atom_setfloat(*av, x->objvalue);
    }
    return MAX_ERR_NONE;
}
 *
 * @remark  By convention, and to permit the interoperability of objects using the obex API, developers should allocate memory in their <tt>getvalueof</tt> methods using the <tt>getbytes</tt> function. 
@endcode
 *
 */

// function: object_setvalueof
/**
 * Sets the value of an object which supports the <tt>getvalueof/setvalueof</tt> interface. See part 2 of the pattr SDK for more information on this interface.
 *
 * @param   x       The object whose value is of interest
 * @param   ac      The count of arguments in <tt>av</tt>
 * @param   av      Array of t_atoms; the new desired data for the object
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  Developers wishing to design objects which will support this function being called on them must define and implement a special method, <tt>setvalueof</tt>, like so:
@code
class_addmethod(c, (method)myobject_setvalueof, "setvalueof", A_CANT, 0);
@endcode
 *
 * @remark  The <tt>setvalueof</tt> method should be prototyped as:
@code
t_max_err myobject_setvalueof(t_myobject *x, long *ac, t_atom **av);
@endcode
 *
 * @remark  And implemented, generally, as:
@code
t_max_err myobject_setvalueof(t_myobject *x, long ac, t_atom *av)
{
    if (ac && av) {
        // simulate receipt of a float value
        myobject_float(x, atom_getfloat(av));
    }
    return MAX_ERR_NONE;
}
@endcode
 *
 */

</category>

<category>
<cattitle>Object Functions: registration/notification</cattitle>

// function: object_register
/**
 * Registers an object in a namespace.
 *
 * @param   name_space  The namespace in which to register the object. The namespace c
 *                      an be any symbol. If the namespace does not already exist, 
 *                      it is created automatically.
 * @param   s           The name of the object in the namespace. This name will be 
 *                      used by other objects to attach and detach from the registered object.
 * @param   x           The object to register
 *
 * @return  The function returns a pointer to the registered object. Under some 
 *          circumstances, object_register will <em>duplicate</em> the object, 
 *          and return a pointer to the duplicate—the developer should not assume 
 *          that the pointer passed in is the same pointer that has been registered. 
 *          To be safe, the returned pointer should be stored and used with the 
 *          <tt>object_unregister()</tt> function.
 *
 */

// function: object_unregister
/**
 * Removes a registered object from a namespace.
 *
 * @param   x       The object to unregister. This should be the pointer returned from the <tt>object_register</tt> function.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attach
/**
 * Attaches a client to a registered object. Once attached, the object will receive notifications sent from the registered object (via the <tt>object_notify</tt> function), if it has a <tt>notify</tt> method defined and implemented. See below for more information, in the reference for <tt>object_notify</tt>.
 *
 * @param   name_space  The namespace of the registered object. This should be the 
 *                      same value used in <tt>object_register</tt> to register the 
 *                      object. If you don't know the registered object's namespace, 
 *                      the <tt>object_findregisteredbyptr</tt> function can be 
 *                      used to determine it.
 * @param   s           The name of the registered object in the namespace. If you 
 *                      don't know the name of the registered object, the 
 *                      <tt>object_findregisteredbyptr</tt> function can be used to 
 *                      determine it.
 * @param   x           The client object to attach. Generally, this is the pointer to your Max object. 
 *
 * @return  This function returns a pointer to the registered object (to the object 
 *          referred to by the combination of <tt>name_space</tt> and <tt>s</tt> 
 *          arguments) if successful, or NULL if unsuccessful.
 *
 */

// function: object_detach
/**
 * Detach a client from a registered object.
 *
 * @param   name_space  The namespace of the registered object. This should be the 
 *                      same value used in <tt>object_register</tt> to register the 
 *                      object. If you don't know the registered object's namespace, 
 *                      the <tt>object_findregisteredbyptr</tt> function can be 
 *                      used to determine it.
 * @param   s           The name of the registered object in the namespace. If you 
 *                      don't know the name of the registered object, the 
 *                      <tt>object_findregisteredbyptr</tt> function can be used to 
 *                      determine it.
 * @param   x           The client object to detach. Generally, this is the pointer to your Max object. 
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_notify
/**
 * Broadcast a message (with an optional argument) from a registered object to any attached client objects.
 *
 * @param   x       Pointer to the registered object
 * @param   s       The message to send
 * @param   data    An optional argument which will be passed with the message. 
 *                  Sets this argument to <tt>NULL</tt> if it will be unused. 
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  In order for client objects to receive notifications, they must define and implement a special method, <tt>notify</tt>, like so:
@code
class_addmethod(c, (method)myobject_notify, "notify", A_CANT, 0);
@endcode
 *
 * @remark  The <tt>notify</tt> method should be prototyped as:
@code
void myobject_notify(t_myobject *x, t_symbol *s, t_symbol *msg, void *sender, void *data);
@endcode
 * where 
 * <tt>x</tt> is the pointer to the receiving object,
 * <tt>s</tt> is the name of the sending (registered) object in its namespace,
 * <tt>msg</tt> is the sent message,
 * <tt>sender</tt> is the pointer to the sending object, and
 * <tt>data</tt>is an optional argument sent with the message. 
 * This value corresponds to the data argument in the <tt>object_notify</tt> method. 
 *
 */

// function: object_findregistered
/**
 * Determines a registered object's pointer, given its namespace and name.
 *
 * @param   name_space  The namespace of the registered object
 * @param   s           The name of the registered object in the namespace
 *
 * @return  This function returns the pointer of the registered object, 
 *          if successful, or NULL, if unsuccessful.
 *
 */

// function: object_findregisteredbyptr
/**
 * Determines the namespace and/or name of a registered object, given the object's pointer.
 *
 * @param   name_space  Pointer to a t_symbol *, to receive the namespace of the registered object
 * @param   s           Pointer to a t_symbol *, to receive the name of the registered object within the namespace
 * @param   x           Pointer to the registered object
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

</category>

<category>
<cattitle>Attribute Functions: attribute creation and filters</cattitle>
/**
 *
 * @remark  Attributes have been described at length elsewhere. They can be added to a class using the <tt>class_addattr</tt> function. The following functions provide means of creating and modifying attribute filter properties.
 *
 */

// function: attribute_new
/**
 * Create a new attribute. The attribute will allocate memory and store its own data. Attributes created using <tt>attribute_new</tt> can be assigned either to classes (using the <tt>class_addattr</tt> function) or to objects (using the <tt>object_addattr</tt> function).
 *
 * @param   name    A name for the attribute, as a C-string
 * @param   type    A t_symbol * representing a valid attribute type. At the time of this writing, the valid type-symbols are: <tt>_sym_char</tt> (char), <tt>_sym_long</tt> (long), <tt>_sym_float32</tt> (32-bit float), <tt>_sym_float64</tt> (64-bit float), <tt>_sym_atom</tt> (Max t_atom pointer), <tt>_sym_symbol</tt> (Max t_symbol pointer), <tt>_sym_pointer</tt> (generic pointer) and <tt>_sym_object</tt> (Max t_object pointer).
 * @param   flags   Any attribute flags, expressed as a bitfield. Attribute flags are used to determine if an attribute is accessible for setting or querying. The following accessor flags are currently available:ATTR_GET_OPAQUE: The attribute cannot be queried by either max message when used inside of a CLASS_BOX object, nor from C code.ATTR_SET_OPAQUE: The attribute cannot be set by either max message when used inside of a CLASS_BOX object, nor from C code.ATTR_GET_OPAQUE_USER: The attribute cannot be queried by max message when used inside of a CLASS_BOX object, but <em>can</em> be queried from C code.ATTR_SET_OPAQUE_USER: The attribute cannot be set by max message when used inside of a CLASS_BOX object, but <em>can</em> be set from C code.<text:tab-stop/>
 * @param   mget    The method to use for the attribute's <tt>get</tt> functionality. If <tt>mget</tt> is <tt>NULL</tt>, the default method is used. 
 * @param   mset    The method to use for the attribute's <tt>set</tt> functionality. If <tt>mset</tt> is <tt>NULL</tt>, the default method is used.
 *
 * @return  This function returns the new attribute's object pointer if successful, or <tt>NULL</tt> if unsuccessful.
 *
 * @remark  Developers wishing to define custom methods for <tt>get</tt> or <tt>set</tt> functionality need to prototype them as:
@code
t_max_err myobject_myattr_get(t_myobject *x, void *attr, long *ac, t_atom **av);
@endcode
@code
t_max_err myobject_myattr_set(t_myobject *x, void *attr, long ac, t_atom *av);
@endcode
 *
 * @remark  Implementation will vary, of course, but need to follow the following basic models. Note that, as with custom <tt>getvalueof</tt> and <tt>setvalueof</tt> methods for the object, assumptions are made throughout Max that <tt>getbytes</tt> has been used for memory allocation. Developers are strongly urged to do the same:
@code
t_max_err myobject_myattr_get(t_myobject *x, void *attr, long *ac, t_atom **av)
{
    if (*ac && *av)
        // memory passed in; use it
    else {
        *ac = 1; // size of attr data
        *av = (t_atom *)getbytes(sizeof(t_atom) * (*ac));
        if (!(*av)) {
            *ac = 0;
            return MAX_ERR_OUT_OF_MEM;
        }
    }
    atom_setlong(*av, x->some_value);
    return MAX_ERR_NONE;
}

t_max_err myobject_myattr_set(t_myobject *x, void *attr, long ac, t_atom *av)
{
    if (ac && av) {
        x->some_value = atom_getlong(av);
    }
    return MAX_ERR_NONE;
}
@endcode
 *
 */

// function: attr_offset_new
/**
 * Create a new attribute. The attribute references memory stored outside of itself, in the object's data structure. Attributes created using <tt>attr_offset_new</tt> can be assigned either to classes (using the <tt>class_addattr</tt> function) or to objects (using the <tt>object_addattr</tt> function).
 *
 * @param   name    A name for the attribute, as a C-string
 * @param   type    A t_symbol * representing a valid attribute type. At the time of this writing, the valid type-symbols are: <tt>_sym_char</tt> (char), <tt>_sym_long</tt> (long), <tt>_sym_float32</tt> (32-bit float), <tt>_sym_float64</tt> (64-bit float), <tt>_sym_atom</tt> (Max t_atom pointer), <tt>_sym_symbol</tt> (Max t_symbol pointer), <tt>_sym_pointer</tt> (generic pointer) and <tt>_sym_object</tt> (Max t_object pointer). This type should match the size of the data at the byte offset specified in the <tt>offset</tt> argument.
 * @param   flags   Any attribute flags, expressed as a bitfield. See the discussion of attribute flags above, under <tt>attribute_new()</tt>.
 * @param   mget    The method to use for the attribute's <tt>get</tt> functionality. If <tt>mget</tt> is <tt>NULL</tt>, the default method is used. See the discussion under <tt>attribute_new</tt>, above, for more information.
 * @param   mset    The method to use for the attribute's <tt>set</tt> functionality. If <tt>mset</tt> is <tt>NULL</tt>, the default method is used. See the discussion under <tt>attribute_new</tt>, above, for more information.
 * @param   offset  Byte offset into the class data structure of the object which will "own" the attribute. The offset should point to the data to be referenced by the attribute. Typically, the <tt>calcoffset</tt> macro (described above) is used to calculate this offset.
 *
 * @return  This function returns the new attribute's object pointer if successful, or <tt>NULL</tt> if unsuccessful.
 *
 * @remark  For instance, to create a new attribute which references the value of a double variable (<tt>val</tt>) in an object class's data structure:
@code
t_object *attr = attr_offset_new("myattr", _sym_float64 / * matches data size * /, 0 / * no flags * /, (method)0L, (method)0L, calcoffset(t_myobject, val));
@endcode
 *
 */

// function: attr_offset_array_new
/**
 * Create a new attribute. The attribute references an array of memory stored outside of itself, in the object's data structure. Attributes created using <tt>attr_offset_array_new</tt> can be assigned either to classes (using the <tt>class_addattr</tt> function) or to objects (using the <tt>object_addattr</tt> function).
 *
 * @param   name        A name for the attribute, as a C-string
 * @param   type        A t_symbol * representing a valid attribute type. At the time of this writing, the valid type-symbols are: <tt>_sym_char</tt> (char), <tt>_sym_long</tt> (long), <tt>_sym_float32</tt> (32-bit float), <tt>_sym_float64</tt> (64-bit float), <tt>_sym_atom</tt> (Max t_atom pointer), <tt>_sym_symbol</tt> (Max t_symbol pointer), <tt>_sym_pointer</tt> (generic pointer) and <tt>_sym_object</tt> (Max t_object pointer). This type should match the size of the data at the byte offset specified in the <tt>offset</tt> argument.
 * @param   size        The maximum number of elements the array of data will contain. 
 * @param   flags       Any attribute flags, expressed as a bitfield. See the discussion of attribute flags above, under <tt>attribute_new()</tt>.
 * @param   mget        The method to use for the attribute's <tt>get</tt> functionality. If <tt>mget</tt> is <tt>NULL</tt>, the default method is used. See the discussion under <tt>attribute_new</tt>, above, for more information.
 * @param   mset        The method to use for the attribute's <tt>set</tt> functionality. If <tt>mset</tt> is <tt>NULL</tt>, the default method is used. See the discussion under <tt>attribute_new</tt>, above, for more information.
 * @param   offsetcount Byte offset into the object class's data structure of a long variable describing how many array elements (up to <tt>size</tt>) comprise the data to be referenced by the attribute. Typically, the <tt>calcoffset</tt> macro (described above) is used to calculate this offset.
 * @param   offset      Byte offset into the class data structure of the object which will "own" the attribute. The offset should point to the data to be referenced by the attribute. Typically, the <tt>calcoffset</tt> macro (described above) is used to calculate this offset.
 *
 * @return  This function returns the new attribute's object pointer if successful, or <tt>NULL</tt> if unsuccessful.
 *
 * @remark  For instance, to create a new attribute which references an array of 10 t_atoms (<tt>atm</tt>; the current number of "active" elements in the array is held in the variable <tt>atmcount</tt>) in an object class's data structure:
@code
t_object *attr = attr_offset_array_new("myattrarray", _sym_atom / * matches data size * /, 10 / * max * /, 0 / * no flags * /, (method)0L, (method)0L, calcoffset(t_myobject, atmcount) / * count * /, calcoffset(t_myobject, atm) / * data * /);
@endcode
 *
 */

// function: attr_addfilter_clip
/**
 * Attaches a clip filter to an attribute. The filter will clip any values sent to or retrieved from the attribute using the attribute's <tt>get</tt> and <tt>set</tt> functions.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   min     Minimum value for the clip filter
 * @param   max     Maximum value for the clip filter 
 * @param   usemin  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 * @param   usemax  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: attr_addfilter_clip_scale
/**
 * Attaches a clip/scale filter to an attribute. The filter will clip and scale any values sent to or retrieved from the attribute using the attribute's <tt>get</tt> and <tt>set</tt> functions.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   scale   Scale value. Data sent to the attribute will be scaled by this amount. Data retrieved from the attribute will be scaled by its reciprocal. <em>Scaling occurs previous to clipping</em>.
 * @param   min     Minimum value for the clip filter
 * @param   max     Maximum value for the clip filter 
 * @param   usemin  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 * @param   usemax  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: attr_addfilterset_clip
/**
 * Attaches a clip filter to an attribute. The filter will <em>only</em> clip values sent to the attribute using the attribute's <tt>set</tt> function.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   min     Minimum value for the clip filter
 * @param   max     Maximum value for the clip filter 
 * @param   usemin  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 * @param   usemax  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: attr_addfilterset_clip_scale
/**
 * Attaches a clip/scale filter to an attribute. The filter will <em>only</em> clip and scale values sent to the attribute using the attribute's <tt>set</tt> function.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   scale   Scale value. Data sent to the attribute will be scaled by this amount. <em>Scaling occurs previous to clipping</em>.
 * @param   min     Minimum value for the clip filter
 * @param   max     Maximum value for the clip filter 
 * @param   usemin  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 * @param   usemax  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: attr_addfilterget_clip
/**
 * Attaches a clip filter to an attribute. The filter will <em>only</em> clip values retrieved from the attribute using the attribute's <tt>get</tt> function.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   min     Minimum value for the clip filter
 * @param   max     Maximum value for the clip filter 
 * @param   usemin  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 * @param   usemax  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: attr_addfilterget_clip_scale
/**
 * Attaches a clip/scale filter to an attribute. The filter will <em>only</em> clip and scale values retrieved from the attribute using the attribute's <tt>get</tt> function.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   scale   Scale value. Data retrieved from the attribute will be scaled by this amount. <em>Scaling occurs previous to clipping</em>.
 * @param   min     Minimum value for the clip filter
 * @param   max     Maximum value for the clip filter 
 * @param   usemin  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 * @param   usemax  Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: attr_addfilterset_proc
/**
 * Attaches a custom filter method to an attribute. The filter will <em>only</em> be called for values retrieved from the attribute using the attribute's <tt>set</tt> function.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   proc    A filter method
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  The filter method should be prototyped and implemented as follows:
@code
t_max_err myfiltermethod(void *parent, void *attr, long ac, t_atom *av);

t_max_err myfiltermethod(void *parent, void *attr, long ac, t_atom *av)
{
    long i;
    float temp,

    // this filter rounds off all values
    // assumes that the data is float 
    for (i = 0; i < ac; i++) {
        temp = atom_getfloat(av + i);
        temp = (float)((long)(temp + 0.5));
        atom_setfloat(av + i, temp);
    }
    return MAX_ERR_NONE;
}
@endcode
 *
 */

// function: attr_addfilterget_proc
/**
 * Attaches a custom filter method to an attribute. The filter will <em>only</em> be called for values retrieved from the attribute using the attribute's <tt>get</tt> function.
 *
 * @param   x       Pointer to the attribute to receive the filter
 * @param   proc    A filter method
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  The filter method should be prototyped and implemented as described above for the <tt>attr_addfilterset_proc</tt> function.
 *
 */

</category>

<category>
<cattitle>Object Functions: attributes (general)</cattitle>

// function: object_attr_getvalueof
/**
 * Retrieves the value of an object's attribute. 
 *
 * @param   x       Pointer to the object whose attribute is of interest
 * @param   s       The attribute's name
 * @param   argc    Pointer to a long variable to receive the count of arguments in <tt>argv</tt>. The long variable itself should be set to 0 previous to calling this function.
 * @param   argv    Pointer to a t_atom *, to receive object data. The t_atom * itself should be set to <tt>NULL</tt> previous to calling this function.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  Calling the <tt>object_getvalueof</tt> function allocates memory for any data it returns. It is the developer's responsibility to free it, using the <tt>freebytes</tt> function.
 *
 */

// function: object_attr_setvalueof
/**
 * Sets the value of an object's attribute. 
 *
 * @param   x       Pointer to the object whose attribute is of interest
 * @param   s       The attribute's name
 * @param   argc    The count of arguments in <tt>argv</tt>
 * @param   argv    Array of t_atoms; the new desired data for the attribute
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_get
/**
 * Returns the pointer to an attribute, given its name. 
 *
 * @param   x           Pointer to the object whose attribute is of interest
 * @param   attrname    The attribute's name
 *
 * @return  This function returns a pointer to the attribute, if successful, or <tt>NULL</tt>, if unsuccessful.
 *
 */

// function: object_attr_method
/**
 * Returns the method of an attribute's <tt>get</tt> or <tt>set</tt> function, as well as a pointer to the attribute itself, from a message name. 
 *
 * @param   x           Pointer to the object whose attribute is of interest
 * @param   methodname  The Max message used to call the attribute's <tt>get</tt> or <tt>set</tt> function. For example, <tt>gensym("mode")</tt> or <tt>gensym("getthresh")</tt>.
 * @param   attr        A pointer to a void *, which will be set to the attribute pointer upon successful completion of the function
 * @param   get         A pointer to a long variable, which will be set to 1 upon successful completion of the function, if the queried method corresponds to the <tt>get</tt> function of the attribute. 
 *
 * @return  This function returns the requested method, if successful, or <tt>NULL</tt>, if unsuccessful.
 *
 */

// function: object_attr_usercanset
/**
 * Determines if an object's attribute can be set from the Max interface (i.e. if its <tt>ATTR_SET_OPAQUE_USER</tt> flag is set). 
 *
 * @param   x       Pointer to the object whose attribute is of interest
 * @param   s       The attribute's name
 *
 * @return  This function returns 1 if the attribute can be set from the Max interface. Otherwise, it returns 0. 
 *
 */

// function: object_attr_usercanget
/**
 * Determines if the value of an object's attribute can be queried from the Max interface (i.e. if its <tt>ATTR_GET_OPAQUE_USER</tt> flag is set). 
 *
 * @param   x       Pointer to the object whose attribute is of interest
 * @param   s       The attribute's name
 *
 * @return  This function returns 1 if the value of the attribute can be queried from the Max interface. Otherwise, it returns 0.
 *
 */

// function: object_attr_getdump
/**
 * Forces a specified object's attribute to send its value from the object's dumpout outlet in the Max interface. 
 *
 * @param   x       Pointer to the object whose attribute is of interest
 * @param   s       The attribute's name
 * @param   argc    Unused
 * @param   argv    Unused
 *
 */

</category>

<category>
<cattitle>Object Functions: attributes (object attributes)</cattitle>

// function: object_addattr
/**
 * Attaches an attribute directly to an object. 
 *
 * @param   x       An object to which the attribute should be attached
 * @param   attr    The attribute's pointer—this should be a pointer returned from <tt>attribute_new</tt>, <tt>attr_offset_new</tt> or <tt>attr_offset_array_new</tt>.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_deleteattr
/**
 * Detach an attribute from an object that was previously attached with <tt>object_addattr</tt>. The function will also free all memory associated with the attribute. If you only wish to detach the attribute, without freeing it, see the <tt>object_chuckattr</tt> function, below.
 *
 * @param   x           The object to which the attribute is attached
 * @param   attrsym     The attribute's name
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_chuckattr
/**
 * Detach an attribute from an object that was previously attached with <tt>object_addattr</tt>. This function will not free the attribute (use <tt>object_free</tt> to do this manually).
 *
 * @param   x           The object to which the attribute is attached
 * @param   attrsym     The attribute's name
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

</category>

<category>
<cattitle>Attribute Functions: attribute arguments</cattitle>
/**
 *
 * @remark  Most objects which implement attributes support the use of attributes on a Max object's "command line"—written directly in the object box using the form <tt>@attributename value</tt>. The following functions implement this functionality.
 *
 * @remark  NOTE: Because attribute arguments rely on atom lists of the <tt>argc</tt>/<tt>argv</tt> variety, developers who wish to support them must implement their objects as <tt>A_GIMME</tt> in their call to <tt>class_new</tt>.
 */

// function: attr_args_process
/**
 * Take an atom list and properly set any attributes described within. This function is typically used in an object's <tt>new</tt> method to conveniently process attribute arguments.
 *
 * @param   x       The object whose attributes will be processed
 * @param   ac      The count of t_atoms in <tt>av</tt>
 * @param   av      An atom list
 *
 * @remark  Here is a typical example of usage:
@code
void *myobject_new(t_symbol *s, long ac, t_atom *av)
{
    t_myobject *x = NULL;

    if (x=(t_myobject *)object_alloc(myobject_class))
    {
        // initialize any data before processing
        // attributes to avoid overwriting 
        // attribute argument-set values
        x->data = 0; 

        // process attr args, if any
        attr_args_process(x, ac, av);
    }
    return x;
}
@endcode
 *
 */

// function: attr_args_offset
/**
 * Determines the point in an atom list where attribute arguments begin. Developers can use this function to assist in the manual processing of attribute arguments, when attr_args_process doesn't provide the correct functionality for a particular purpose.
 *
 * @param   ac      The count of t_atoms in <tt>av</tt>
 * @param   av      An atom list
 *
 * @return  This function returns an offset into the atom list, where the first attribute argument occurs. For instance, the atom list <tt>foo bar 3.0 @mode 6</tt> would cause <tt>attr_args_offset</tt> to return 3 (the attribute <tt>mode</tt> appears at position 3 in the atom list).
 *
 */

</category>

<category>
<cattitle>Object Functions: attribute utility functions (single value functions)</cattitle>

// function: object_attr_getlong
/**
 * Retrieves the value of an attribute, given its parent object and name. 
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 *
 * @return  This function returns the value of the specified attribute, if successful, or 0, if unsuccessful.
 *
 * @remark  If the attribute is not of the type specified by the function, the 
 *          function will attempt to coerce a valid value from the attribute.
 *
 */

// function: object_attr_getfloat
/**
 * Retrieves the value of an attribute, given its parent object and name. 
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 *
 * @return  This function returns the value of the specified attribute, if successful, or 0, if unsuccessful.
 *
 * @remark  If the attribute is not of the type specified by the function, the 
 *          function will attempt to coerce a valid value from the attribute.
 *
 */

// function: object_attr_getsym
/**
 * Retrieves the value of an attribute, given its parent object and name. 
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 *
 * @return  This function returns the value of the specified attribute, if successful, or the empty symbol (equivalent to <tt>gensym("")</tt> or <tt>_sym_nothing</tt>), if unsuccessful.
 *
 */

// function: object_attr_setlong
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   c       An integer value; the new value for the attribute
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_setfloat
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   c       An floating point value; the new value for the attribute
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_setsym
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   c       A t_symbol *; the new value for the attribute
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

</category>

<category>
<cattitle>Object Functions: attribute utility functions (multiple value functions)</cattitle>
 *
 * @remark  The following functions provide access to arrays of attribute values. They can be used with any attribute.

// function: object_attr_getlong_array
/**
 * Retrieves the value of an attribute, given its parent object and name. This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the <tt>object_attr_getvalueof</tt> function.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   max     The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array.
 * @param   vals    Pointer to the first element of a pre-allocated array of long data.
 *
 * @return  This function returns the number of elements copied into <tt>vals</tt>.
 *
 * @remark  If the attribute is not of the type specified by the function, the 
 *          function will attempt to coerce a valid value from the attribute.
 *
 */

// function: object_attr_getchar_array
/**
 * Retrieves the value of an attribute, given its parent object and name. This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the <tt>object_attr_getvalueof</tt> function.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   max     The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array.
 * @param   vals    Pointer to the first element of a pre-allocated array of unsigned char data.
 *
 * @return  This function returns the number of elements copied into <tt>vals</tt>.
 *
 * @remark  If the attribute is not of the type specified by the function, the 
 *          function will attempt to coerce a valid value from the attribute.
 *
 */

// function: object_attr_getfloat_array
/**
 * Retrieves the value of an attribute, given its parent object and name. This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the <tt>object_attr_getvalueof</tt> function.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   max     The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array.
 * @param   vals    Pointer to the first element of a pre-allocated array of float data.
 *
 * @return  This function returns the number of elements copied into <tt>vals</tt>.
 *
 * @remark  If the attribute is not of the type specified by the function, the 
 *          function will attempt to coerce a valid value from the attribute.
 *
 */

// function: object_attr_getdouble_array
/**
 * Retrieves the value of an attribute, given its parent object and name. This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the <tt>object_attr_getvalueof</tt> function.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   max     The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array.
 * @param   vals    Pointer to the first element of a pre-allocated array of double data.
 *
 * @return  This function returns the number of elements copied into <tt>vals</tt>.
 *
 * @remark  If the attribute is not of the type specified by the function, the 
 *          function will attempt to coerce a valid value from the attribute.
 *
 */

// function: object_attr_getsym_array
/**
 * Retrieves the value of an attribute, given its parent object and name. This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the <tt>object_attr_getvalueof</tt> function.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   max     The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array.
 * @param   vals    Pointer to the first element of a pre-allocated array of t_symbol *s.
 *
 * @return  This function returns the number of elements copied into <tt>vals</tt>.
 *
 */

// function: object_attr_setlong_array
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   count   The number of array elements in vals
 * @param   vals    Pointer to the first element of an array of long data
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_setchar_array
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   count   The number of array elements in vals
 * @param   vals    Pointer to the first element of an array of unsigned char data
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_setfloat_array
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   count   The number of array elements in vals
 * @param   vals    Pointer to the first element of an array of float data
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_setdouble_array
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   count   The number of array elements in vals
 * @param   vals    Pointer to the first element of an array of double data
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_attr_setsym_array
/**
 * Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided.
 *
 * @param   x       The attribute's parent object
 * @param   s       The attribute's name
 * @param   count   The number of array elements in vals
 * @param   vals    Pointer to the first element of an array of t_symbol *s
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

</category>

<category>
<cattitle>Atom Utilities</cattitle>
 *
 * @remark  Also present in "ext_obex.c" are some new atom utilities, used to get and set t_atom values. Direct access to t_atoms continues to be supported, but many developers may find these utilities more succinct and safe. 

// function: atom_setlong
/**
 * Inserts an integer into a t_atom and change the t_atom's type to <tt>A_LONG</tt>. 
 *
 * @param   a       Pointer to a t_atom whose value and type will be modified
 * @param   b       Integer value to copy into the t_atom
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: atom_setfloat
/**
 * Inserts a floating point number into a t_atom and change the t_atom's type to <tt>A_FLOAT</tt>. 
 *
 * @param   a       Pointer to a t_atom whose value and type will be modified
 * @param   b       Floating point value to copy into the t_atom
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: atom_setsym
/**
 * Inserts a t_symbol * into a t_atom and change the t_atom's type to <tt>A_SYM</tt>. 
 *
 * @param   a       Pointer to a t_atom whose value and type will be modified
 * @param   b       Pointer to a t_symbol to copy into the t_atom
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: atom_setobj
/**
 * Inserts a generic pointer value into a t_atom and change the t_atom's type to <tt>A_OBJ</tt>. 
 *
 * @param   a       Pointer to a t_atom whose value and type will be modified
 * @param   b       Pointer value to copy into the t_atom
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: atom_getlong
/**
 * Retrieves a long integer value from a t_atom. 
 *
 * @param   a       Pointer to a t_atom whose value is of interest
 *
 * @return  This function returns the value of the specified t_atom as an integer, if possible. Otherwise, it returns 0. 
 *
 * @remark  If the t_atom is not of the type specified by the function, the function will attempt to coerce a valid value from the t_atom. For instance, if the t_atom <tt>at</tt> is set to type <tt>A_FLOAT</tt> with a value of <tt>3.7</tt>, the <tt>atom_getlong</tt> function will return the truncated integer value of <tt>at</tt>, or <tt>3</tt>. An attempt is also made to coerce t_symbol data.
 *
 */

// function: atom_getfloat
/**
 * Retrieves a floating point value from a t_atom. 
 *
 * @param   a       Pointer to a t_atom whose value is of interest
 *
 * @return  This function returns the value of the specified t_atom as a floating point number, if possible. Otherwise, it returns 0. 
 *
 * @remark  If the t_atom is not of the type specified by the function, the function will attempt to coerce a valid value from the t_atom. For instance, if the t_atom <tt>at</tt> is set to type <tt>A_LONG</tt> with a value of <tt>5</tt>, the <tt>atom_getfloat</tt> function will return the value of <tt>at</tt> as a float, or <tt>5.0</tt>. An attempt is also made to coerce t_symbol data.
 *
 */

// function: atom_getsym
/**
 * Retrieves a t_symbol * value from a t_atom. 
 *
 * @param   a       Pointer to a t_atom whose value is of interest
 *
 * @return  This function returns the value of the specified <tt>A_SYM</tt>-typed t_atom, if possible. Otherwise, it returns an empty, but valid, t_symbol *, equivalent to <tt>gensym("")</tt>, or <tt>_sym_nothing</tt>. 
 *
 * @remark  No attempt is made to coerce non-matching data types. 
 *
 */

// function: atom_getobj
/**
 * Retrieves a generic pointer value from a t_atom. 
 *
 * @param   a       Pointer to a t_atom whose value is of interest
 *
 * @return  This function returns the value of the specified <tt>A_OBJ</tt>-typed t_atom, if possible. Otherwise, it returns <tt>NULL</tt>. 
 *
 * @remark  If the t_atom is typed <tt>A_LONG</tt>, but the data falls outside of the range 0-255, the data is truncated to that range before output.
 *
 */

// function: atom_getcharfix
/**
 * Retrieves an unsigned integer value between 0 and 255 from a t_atom. 
 *
 * @param   a       Pointer to a t_atom whose value is of interest
 *
 * @return  This function returns the value of the specified t_atom as an integer between 0 and 255, if possible. Otherwise, it returns 0. 
 *
 * @remark  If the t_atom is typed <tt>A_LONG</tt>, but the data falls outside of the range 0-255, the data is truncated to that range before output.
 *
 * @remark  If the t_atom is typed <tt>A_FLOAT</tt>, the floating point value is multiplied by 255. and truncated to the range 0-255 before output. For example, the floating point value <tt>0.5</tt> would be output from atom_getcharfix as <tt>127</tt> (0.5 * 255. = 127.5). 
 *
 * @remark  No attempt is also made to coerce t_symbol data. 
 *
 */

// function: atom_arg_getlong
/**
 * Retrieves the integer value of a particular t_atom from an atom list, if the atom exists.
 *
 * @param   c       Pointer to a long variable to receive the atom's data if the function is successful.
 * @param   idx     Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2.
 * @param   ac      Count of av.
 * @param   av      Pointer to the first t_atom of an atom list.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  The <tt>atom_arg_getlong</tt> function only changes the value of <tt>c</tt> if the function is successful. For instance, the following code snippet illustrates a simple, but typical use:
@code
void myobject_mymessage(t_myobject *x, t_symbol *s, long ac, t_atom *av)
{
    long var = -1;

    // here, we are expecting a value of 0 or greater
    atom_arg_getlong(&var, 0, ac, av);
    if (val == -1) // i.e. unchanged
        post("it is likely that the user did not provide a valid argument");
    else {
        ...
    }
}
@endcode
 *
 */

// function: atom_arg_getfloat
/**
 * Retrieves the floating point value of a particular t_atom from an atom list, if the atom exists.
 *
 * @param   c       Pointer to a float variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged.
 * @param   idx     Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2.
 * @param   ac      Count of av.
 * @param   av      Pointer to the first t_atom of an atom list.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: atom_arg_getdouble
/**
 * Retrieves the floating point value, as a double, of a particular t_atom from an atom list, if the atom exists.
 *
 * @param   c       Pointer to a double variable to receive the atom's data if the function is successful. Otherwise the value is left unchanged.
 * @param   idx     Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2.
 * @param   ac      Count of av.
 * @param   av      Pointer to the first t_atom of an atom list.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: atom_arg_getsym
/**
 * Retrieves the t_symbol * value of a particular t_atom from an atom list, if the atom exists.
 *
 * @param   c       Pointer to a t_symbol * variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged.
 * @param   idx     Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2.
 * @param   ac      Count of av.
 * @param   av      Pointer to the first t_atom of an atom list.
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 * @remark  The <tt>atom_arg_getsym</tt> function only changes the value of <tt>c</tt> if the function is successful. For instance, the following code snippet illustrates a simple, but typical use:
@code
void myobject_open(t_myobject *x, t_symbol *s, long ac, t_atom *av)
{
    t_symbol *filename = _sym_nothing;

    // here, we are expecting a file name.
    // if we don't get it, open a dialog box 
    atom_arg_getsym(&filename, 0, ac, av);
    if (filename == _sym_nothing) { // i.e. unchanged
        // open the file dialog box,
        // get a value for filename
    }
    // do something with the filename
}
@endcode
 *
 */

</category>

<category>
<cattitle>Miscellaneous Utilities</cattitle>

// function: symbol_unique
/**
 * Generates a unique t_symbol *. The symbol will be formatted somewhat like "u123456789". 
 *
 *
 * @return  This function returns a unique t_symbol *.
 *
 */

// function: error_sym
/**
 * Posts an error message to the Max window. This function is interrupt safe. 
 *
 * @param   x       The object's pointer
 * @param   s       Symbol to be posted as an error in the Max window
 *
 */

// function: post_sym
/**
 * Posts a message to the Max window. This function is interrupt safe. 
 *
 * @param   x       The object's pointer
 * @param   s       Symbol to be posted in the Max window
 *
 */

// function: symbolarray_sort
/**
 * Performs an ASCII sort on an array of t_symbol *s.
 *
 * @param   ac      The count of t_symbol *s in <tt>av</tt>
 * @param   av      An array of t_symbol *s to be sorted
 *
 * @return  This function returns the error code <tt>MAX_ERR_NONE</tt> if successful, 
 *          or one of the other error codes defined in "ext_obex.h" if unsuccessful.
 *
 */

// function: object_obex_quickref
/**
 * Developers do not need to directly use the <tt>object_obex_quickref</tt> function. However, to take advantage of a new quickref appearance, which provides support for attributes, developers should define the following method in <tt>main()</tt>.
 *
@code
class_addmethod(c / * your object class * /, (method)object_obex_quickref, "quickref", A_CANT,0);
@endcode
 *
 */

</category>

Copyright © 2008, Cycling '74