[vlc-devel] commit: vlc_object_find_name: return vlc_object_t * ( Rémi Denis-Courmont )

[git version control]

vlc | branch: master | Rémi Denis-Courmont <rdenis at simphalempin.com> | Sat Sep  6 16:10:32 2008 +0300| [cd133b2d01d94380ebe055d00e08dc49756a8493] | committer: Rémi Denis-Courmont 

vlc_object_find_name: return vlc_object_t *

Casting to any other type would be (is?) unsafe as users can now freely
alias objects.

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=cd133b2d01d94380ebe055d00e08dc49756a8493
---

 include/vlc_objects.h |    4 ++--
 src/libvlccore.sym    |    2 +-
 src/misc/objects.c    |   26 ++++++++++++++++++--------
 3 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/include/vlc_objects.h b/include/vlc_objects.h
index 7e8a61c..bf568ed 100644
--- a/include/vlc_objects.h
+++ b/include/vlc_objects.h
@@ -85,7 +85,7 @@ __attribute__((deprecated))
 #endif
 VLC_EXPORT( void *, vlc_object_get, ( libvlc_int_t *, int ) );
 VLC_EXPORT( void *, __vlc_object_find, ( vlc_object_t *, int, int ) );
-VLC_EXPORT( void *, __vlc_object_find_name, ( vlc_object_t *, const char *, int ) );
+VLC_EXPORT( vlc_object_t *, vlc_object_find_name, ( vlc_object_t *, const char *, int ) );
 VLC_EXPORT( void, __vlc_object_yield, ( vlc_object_t * ) );
 VLC_EXPORT( void, __vlc_object_release, ( vlc_object_t * ) );
 VLC_EXPORT( vlc_list_t *, __vlc_list_find, ( vlc_object_t *, int, int ) );
@@ -110,7 +110,7 @@ VLC_EXPORT( void, vlc_list_release, ( vlc_list_t * ) );
     __vlc_object_find( VLC_OBJECT(a),b,c)
 
 #define vlc_object_find_name(a,b,c) \
-    __vlc_object_find_name( VLC_OBJECT(a),b,c)
+    vlc_object_find_name( VLC_OBJECT(a),b,c)
 
 #define vlc_object_yield(a) \
     __vlc_object_yield( VLC_OBJECT(a) )
diff --git a/src/libvlccore.sym b/src/libvlccore.sym
index 2ae280c..133f8fb 100644
--- a/src/libvlccore.sym
+++ b/src/libvlccore.sym
@@ -469,7 +469,7 @@ __vlc_object_attach
 __vlc_object_create
 __vlc_object_detach
 __vlc_object_find
-__vlc_object_find_name
+vlc_object_find_name
 vlc_object_get
 __vlc_object_kill
 __vlc_object_lock
diff --git a/src/misc/objects.c b/src/misc/objects.c
index e6e8f0a..83512ee 100644
--- a/src/misc/objects.c
+++ b/src/misc/objects.c
@@ -620,15 +620,25 @@ void * __vlc_object_find( vlc_object_t *p_this, int i_type, int i_mode )
     return p_found;
 }
 
+#undef vlc_object_find_name
 /**
- ****************************************************************************
- * find a named object and increment its refcount
- *****************************************************************************
- * This function recursively looks for a given object name. i_mode can be one
- * of FIND_PARENT, FIND_CHILD or FIND_ANYWHERE.
- *****************************************************************************/
-void * __vlc_object_find_name( vlc_object_t *p_this, const char *psz_name,
-                               int i_mode )
+ * Finds a named object and increment its reference count.
+ * Beware that objects found in this manner can be "owned" by another thread,
+ * be of _any_ type, and be attached to any module (if any). With such an
+ * object reference, you can set or get object variables, emit log messages,
+ * and read write-once object parameters (i_object_id, psz_object_type, etc).
+ * You CANNOT cast the object to a more specific object type, and you
+ * definitely cannot invoke object type-specific callbacks with this.
+ *
+ * @param p_this object to search from
+ * @param psz_name name of the object to search for
+ * @param i_mode search direction: FIND_PARENT, FIND_CHILD or FIND_ANYWHERE.
+ *
+ * @return a matching object (must be released by the caller),
+ * or NULL on error.
+ */
+vlc_object_t *vlc_object_find_name( vlc_object_t *p_this,
+                                    const char *psz_name, int i_mode )
 {
     vlc_object_t *p_found;