Problem: need way to probe library capabilities

As libzmq is compiled with optional transports and security mechanisms,
there is no clean way for applications to determine what capabilities
are actually available in a given libzmq instance.

Solution: provide an API specifically for capability reporting. The
zmq_has () method is meant to be open ended. It accepts a string so
that we can add arbitrary capabilities without breaking existing
applications.

zmq.h also defines ZMQ_HAS_CAPABILITIES when this method is provided.

.gitignore

@@ -94,6 +94,7 @@ tests/test_proxy_chain
 tests/test_bind_src_address
 tests/test_metadata
 tests/test_id2fd
+tests/test_capabilities
 tests/test*.log
 tests/test*.trs
 src/platform.hpp*

doc/Makefile.am

@@ -10,7 +10,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \
     zmq_errno.3 zmq_strerror.3 zmq_version.3 \
     zmq_sendmsg.3 zmq_recvmsg.3 \
     zmq_proxy.3 zmq_proxy_steerable.3 \
-    zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3
+    zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3 zmq_has.3
 
 MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \
     zmq_null.7 zmq_plain.7 zmq_curve.7 zmq_tipc.7

doc/zmq_has.txt

@@ -0,0 +1,43 @@
+zmq_has(3)
+==========
+
+
+NAME
+----
+zmq_has - check a ZMQ capability
+
+
+SYNOPSIS
+--------
+*int zmq_has (const char *capability);*
+
+
+DESCRIPTION
+-----------
+The _zmq_has()_ function shall report whether a specified capability is
+available in the library. This allows bindings and applications to probe
+a library directly, for transport and security options.
+
+Capabilities shall be lowercase strings. The following capabilities are
+defined:
+
+* ipc - the library supports the ipc:// protocol
+* pgm - the library supports the pgm:// protocol
+* tipc - the library supports the tipc:// protocol
+* norm - the library supports the norm:// protocol
+* curve - the library supports the CURVE security mechanism
+* gssapi - the library supports the GSSAPI security mechanism
+
+When this method is provided, the zmq.h header file will define
+ZMQ_HAS_CAPABILITIES.
+
+RETURN VALUE
+------------
+The _zmq_has()_ function shall return 1 if the specified capability is
+provided. Otherwise it shall return 0.
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

include/zmq.h

@@ -358,9 +358,6 @@ ZMQ_EXPORT int zmq_send_const (void *s, const void *buf, size_t len, int flags);
 ZMQ_EXPORT int zmq_recv (void *s, void *buf, size_t len, int flags);
 ZMQ_EXPORT int zmq_socket_monitor (void *s, const char *addr, int events);
 
-ZMQ_EXPORT int zmq_sendmsg (void *s, zmq_msg_t *msg, int flags);
-ZMQ_EXPORT int zmq_recvmsg (void *s, zmq_msg_t *msg, int flags);
-
 /*  Experimental                                                              */
 struct iovec;
 
@@ -396,12 +393,21 @@ ZMQ_EXPORT int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);
 ZMQ_EXPORT int zmq_proxy (void *frontend, void *backend, void *capture);
 ZMQ_EXPORT int zmq_proxy_steerable (void *frontend, void *backend, void *capture, void *control);
 
+/*  Probe library capabilities  */
+
+#define ZMQ_HAS_CAPABILITIES 1
+ZMQ_EXPORT int zmq_has (const char *capability);
+
 /*  Deprecated aliases */
 #define ZMQ_STREAMER 1
 #define ZMQ_FORWARDER 2
 #define ZMQ_QUEUE 3
-/*  Deprecated method */
+
+/*  Deprecated methods */
 ZMQ_EXPORT int zmq_device (int type, void *frontend, void *backend);
+ZMQ_EXPORT int zmq_sendmsg (void *s, zmq_msg_t *msg, int flags);
+ZMQ_EXPORT int zmq_recvmsg (void *s, zmq_msg_t *msg, int flags);
+
 
 #undef ZMQ_EXPORT
 

src/zmq.cpp

@@ -1043,3 +1043,35 @@ int zmq_device (int /* type */, void *frontend_, void *backend_)
         (zmq::socket_base_t*) frontend_,
         (zmq::socket_base_t*) backend_, NULL);
 }
+
+//  Probe library capabilities; for now, reports on transport and security
+
+int zmq_has (const char *capability)
+{
+#if !defined (ZMQ_HAVE_WINDOWS) && !defined (ZMQ_HAVE_OPENVMS)
+    if (strcmp (capability, "ipc") == 0)
+        return true;
+#endif
+#if defined (ZMQ_HAVE_OPENPGM)
+    if (strcmp (capability, "pgm") == 0)
+        return true;
+#endif
+#if defined (ZMQ_HAVE_TIPC)
+    if (strcmp (capability, "tipc") == 0)
+        return true;
+#endif
+#if defined (ZMQ_HAVE_NORM)
+    if (strcmp (capability, "norm") == 0)
+        return true;
+#endif
+#if defined (HAVE_LIBSODIUM)
+    if (strcmp (capability, "curve") == 0)
+        return true;
+#endif
+#if defined (HAVE_LIBGSSAPI_KRB5)
+    if (strcmp (capability, "gssapi") == 0)
+        return true;
+#endif
+    //  Whatever the application asked for, we don't have
+    return false;
+}

tests/Makefile.am

@@ -48,9 +48,10 @@ noinst_PROGRAMS = test_system \
                   test_ipc_wildcard \
                   test_diffserv \
                   test_connect_rid \
-		  test_bind_src_address \
-		  test_metadata\
-		  test_id2fd
+                  test_bind_src_address \
+                  test_metadata \
+                  test_id2fd \
+                  test_capabilities
 
 if !ON_MINGW
 noinst_PROGRAMS += test_shutdown_stress \
@@ -127,6 +128,7 @@ test_connect_rid_SOURCES = test_connect_rid.cpp
 test_bind_src_address_SOURCES = test_bind_src_address.cpp
 test_metadata_SOURCES = test_metadata.cpp
 test_id2fd_SOURCES = test_id2fd.cpp
+test_capabilities_SOURCES = test_capabilities.cpp
 if !ON_MINGW
 test_shutdown_stress_SOURCES = test_shutdown_stress.cpp
 test_pair_ipc_SOURCES = test_pair_ipc.cpp testutil.hpp

tests/test_capabilities.cpp

@@ -0,0 +1,61 @@
+/*
+    Copyright (c) 2007-2014 Contributors as noted in the AUTHORS file
+
+    This file is part of 0MQ.
+
+    0MQ is free software; you can redistribute it and/or modify it under
+    the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation; either version 3 of the License, or
+    (at your option) any later version.
+
+    0MQ is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include "testutil.hpp"
+
+int main (void)
+{
+#if !defined (ZMQ_HAVE_WINDOWS) && !defined (ZMQ_HAVE_OPENVMS)
+    assert (zmq_has ("ipc"));
+#else
+    assert (!zmq_has ("ipc"));
+#endif
+
+#if defined (ZMQ_HAVE_OPENPGM)
+    assert (zmq_has ("pgm"));
+#else
+    assert (!zmq_has ("pgm"));
+#endif
+    
+#if defined (ZMQ_HAVE_TIPC)
+    assert (zmq_has ("tipc"));
+#else
+    assert (!zmq_has ("tipc"));
+#endif
+    
+#if defined (ZMQ_HAVE_NORM)
+    assert (zmq_has ("norm"));
+#else
+    assert (!zmq_has ("norm"));
+#endif
+    
+#if defined (HAVE_LIBSODIUM)
+    assert (zmq_has ("curve"));
+#else
+    assert (!zmq_has ("curve"));
+#endif
+    
+#if defined (HAVE_LIBGSSAPI_KRB5)
+    assert (zmq_has ("gssapi");
+#else
+    assert (!zmq_has ("gssapi"));
+#endif
+
+    return 0;
+}