From cf57a3fb52d51df34581c48457fead238c328e14 Mon Sep 17 00:00:00 2001 From: Dave Renshaw Date: Tue, 6 Feb 2007 15:08:09 +0000 Subject: [PATCH] Updates for new installation and extension mechanism plus MQTT support. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@229148 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/sam/constants.xml | 26 ++++- reference/sam/reference.xml | 219 ++++++++++++++++++++++++++++-------- 2 files changed, 198 insertions(+), 47 deletions(-) diff --git a/reference/sam/constants.xml b/reference/sam/constants.xml index 8308ff4c85..e1cc170a76 100644 --- a/reference/sam/constants.xml +++ b/reference/sam/constants.xml @@ -1,5 +1,5 @@ - +
&reftitle.constants; &extension.constants; @@ -173,6 +173,30 @@ + + + SAM_MQTT + (string) + + + + Connect protocol definition for selecting the MQTT (MQ Telemetry Transport) protocol. + + + + + + SAM_MQTT_CLEANSTART + (string) + + + + Optional connect option to indicate to an MQTT server that all previous connection data + for this client should be removed and that subscriptions should be deleted when the client + disconnects explicitly or unexpectedly. + + + SAM_NON_PERSISTENT diff --git a/reference/sam/reference.xml b/reference/sam/reference.xml index 66c1283c6f..ad0b23f4c6 100644 --- a/reference/sam/reference.xml +++ b/reference/sam/reference.xml @@ -1,5 +1,5 @@ - + SAM - Simple Asynchronous Messaging SAM @@ -16,10 +16,33 @@ messaging operations. For many users the complexities of setting up numerous options can be simply ignored. -
+ + The SAM extension is a framework that provides a very simple API that can be used to + access a number of messaging middleware systems. Currently the package + includes built-in support for the MQTT (MQ Telemetry Transport) messaging protocol and support for the IBM + Messaging and Queuing middleware products. SAM is designed to be readily extended to + support other messaging systems and extension modules may be written in C or PHP. + +
&reftitle.install; + + The SAM framework and MQTT support can be built and used without any other prerequisites. + Support for protocols other than MQTT is provided via a set of libraries and some client + side code referred to as XMS. + + + If you only intend to use the built-in MQTT support then you can build and configure SAM as + an extension or simply refer to "php_sam.php" with a "requires" or "requires_once" clause + in your PHP script. In this case you need only install the code without building the + extension using the pear installer: + + + +
Prerequisites @@ -53,11 +76,11 @@
Linux installation steps - The sam extension is supplied as a PECL module, which - you should be able to download and install in one step as follows: - - + (Depending on your php environment, you will probably need to be root @@ -70,11 +93,18 @@ pear install sam - + + If you intend to use the XMS support to access the IBM Messaging and Queuing family + you must also enable the SAM XMS extension. + + + - If you cannot use the PEAR installer, you can download the extension - and build it manually: +If you cannot use the PEAR installer, you can download the extension and build +it manually: .tgz @@ -95,13 +125,13 @@ make install #you may need to be root for this step
Windows installation steps - Currently you will need to build the sam extension for Windows as - there are no pre-built binaries. The extension can be built using the - standard Windows extension build procedures. +You will probably need to build the sam extension for Windows as there +are only a limited range of pre-built binaries available from the SAM website. +The extension can be built using the standard Windows extension build procedures. You will need the PHP source tree for the version of PHP you wish to - build the SAM extension against which you can obtain from php.net. + build the SAM extension against which you can obtain from php.net. This should be unpacked into a working directory of your choice. @@ -131,9 +161,9 @@ c:\php-build\- Windows Platform SDK which again can be downloaded from the Microsoft web site. - Obtain the SAM extension source using pear (pear download sam) or by - using CVS and copy the files to a new "sam" directory under the "ext" - directory in your PHP source tree. +Obtain the SAM extension source using pear (pecl download sam) or by using +CVS and copy the files to a new "sam" directory under the "ext" directory +in your PHP source tree. To build the extension open a build environment window by going to the @@ -157,32 +187,67 @@ set PATH=..\win32build\bin;%PATH% ]]> - + Run the buildconf.bat command. This should rebuild the configure.js file. - Run the cscript command: - - + + +To build the SAM framework and the XMS support use: + + - The additional parameter passed for sam is the installation path to - the XMS libraries and runtime that were installed as described under - prerequisites at the top of this file. +The additional parameter passed for sam_xms is the installation path to the +XMS libraries and runtime that were installed as described under prerequisites +at the top of this page. You can specify whatever other cscript parameters you require to include or exclude items from the php build or select options. - Assuming all has gone well so far you can now finally run a make! - - + + +Also if you are using the XMS support you must make the sam_xms extensions: + + + + + +If you have used Visual Studio 2005 to build the DLLs please see below for additional steps that +must be carried out before proceeding further. + + +The DLLs created (php_sam.dll and optionally php_sam_xms.dll) can now be copied to the +subdirectory appropriate for your PHP set-up. Make sure that the module(s) are loaded by PHP, by adding following line to + &php.ini; + : + + + + If you intend to use the XMS support to access the IBM Messgaing and Queuing family + you must also enable the SAM XMS extension. + + @@ -195,24 +260,66 @@ nmake php_sam.dll process to ensure the php_sam.dll is able to link with the C runtime libraries at runtime. This step includes the dependancy manifest into the DLL. Switch to the directory where the - php_sam.dll has been generated (usually + php_sam.dll has been generated (usually Release_TS or Debug_TS below the php source directory) and issue the following magic incantation: - + +If you are using the XMS capabilities you will need to do the same with the +SAM XMS DLL: + + + If you build the SAM extension using the compiler and libaries from Microsoft Visual Studio 2005 you will also need to ensure that the runtime components are installed on the system on which you intend to use SAM. This can be accomplished by installing Visual Studio 2005 or - by using the freely distributable + by using the freely distributable runtime package.
+
+ Protocol support and mapping + +The SAM framework can be extended to support other messaging protocols and connection mechanisms. To add +support for a new protocol or connection library a support class has to be defined, either as a C extension +or as a PHP script, and a "factory" script must be created. The support class must implement all the +methods of the SAMConnection class though it should not inherit from SAMConnection. The factory script +will be called by the SAM framework to create an instance of the implemented class. The way SAM chooses +which factory to call is based on the protocol specified as the first parameter of the "connect" call. + + +By default the built-in MQTT support will be used if a connect call specifies a protocol of SAM_MQTT ("mqtt"), for +any other protocol SAM will attempt to use the XMS support extension. To add support for additional +protocols or to modify the default behavior entries may be added to &php.ini; in the [sam] section. The +default mapping is equivalent to the following entries: + + + +As can be seen from these examples the entries take the form of "sam.factory.pppp=xxx" where pppp is the protocol +string specified on the connect call and xxx is a factory suffix. Note: SAM defines constants for these protocol +strings such that SAM_WMQ=wmq, SAM_WPM=wpm, SAM_MQTT=mqtt, etc. + + +When identifying the support code to use on a connect call SAM looks up the protocol name in the &php.ini; entries +and then invokes a factory script named sam_factory_xxx.php. If no entry is found the support will default to XMS. + +
@@ -240,10 +347,10 @@ mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2 connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com, - SAM_PORT => 1506, - SAM_BROKER => mybroker)); + $conn = new SAMConnection(); + $conn->connect(SAM_WMQ, array(SAM_HOST => 'myhost.mycompany.com', + SAM_PORT => 1506, + SAM_BROKER => 'mybroker')); ?> ]]> @@ -255,15 +362,29 @@ $conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com, connect(SAM_WMQ, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', - SAM_BUS => 'Bus1', - SAM_TARGETCHAIN => 'InboundBasicMessaging')); + $conn = new SAMConnection(); + $conn->connect(SAM_WPM, array(SAM_ENDPOINTS => 'localhost:7278:BootstrapBasicMessaging', + SAM_BUS => 'Bus1', + SAM_TARGETCHAIN => 'InboundBasicMessaging')); ?> ]]> + + + Creating a connection and connecting to an MQTT server + + connect(SAM_MQTT, array(SAM_HOST => 'myhost.mycompany.com', + SAM_PORT => 1883)); +?> + ]]> + + +
@@ -386,8 +507,8 @@ if (!$correlid) { otherwise identical to the point to point model. - By default, SAM creates non-durable subscriptions when using - publish/subscribe. This means that if a client application is + By default, SAM creates non-durable subscriptions when using + publish/subscribe. This means that if a client application is inactive when messages are published to a topic, then it will not receive them when it subsequently restarted. SAM does also allow durable subscriptions to be made to topics when using WPM or WebSphere @@ -398,9 +519,9 @@ if (!$correlid) { Durable subscriptions are specified by using the SAMConnect "subscribe" call. This method takes the destination topic as an input parameter and - returns a subscription identifier that may be used on subsequent + returns a subscription identifier that may be used on subsequent "receive" calls. When the subscription is no longer required the - SAMConnection "unsubscribe" method should be used to delete the + SAMConnection "unsubscribe" method should be used to delete the subscription. @@ -490,7 +611,7 @@ if (!$conn->unsubscribe($subName)) { Error handling All SAMConnection methods that provide access to messaging operations - return &false; if an error occurred in processing the request. + return &false; if an error occurred in processing the request. In addition the SAMConnection object has two properties, "errno" and "error", that provide respectively the error number and text description of the last error to occur on the connection. @@ -593,10 +714,10 @@ if (!$correlid) { peekAll - - a method that receives one or messages from a queue without + - a method that receives one or messages from a queue without removing them from the queue. - + receive @@ -621,6 +742,12 @@ if (!$correlid) { - a method that sends a message to a queue or posts to a topic + + + setDebug + - a method that switches additional debugging output on or off + + subscribe