sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updates for new installation and extension mechanism plus MQTT support.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@229148 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Dave Renshaw 2007-02-06 15:08:09 +00:00
parent b452924294
commit cf57a3fb52
2 changed files with 198 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
reference/sam/constants.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<section id="mq.constants">
&reftitle.constants;
&extension.constants;
@ -173,6 +173,30 @@
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_MQTT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Connect protocol definition for selecting the MQTT (MQ Telemetry Transport) protocol.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_MQTT_CLEANSTART</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>SAM_NON_PERSISTENT</constant>

219
reference/sam/reference.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<reference id="ref.sam">
<title>SAM - Simple Asynchronous Messaging</title>
<titleabbrev>SAM</titleabbrev>
@ -16,10 +16,33 @@
messaging operations. For many users the complexities of setting up
numerous options can be simply ignored.
</para>
</section>
<para>
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.
</para>
</section> <!-- id=sam.intro -->
<section id='sam.installation'>
&reftitle.install;
<para>
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.
</para>
<para>
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:
<screen>
<![CDATA[
pecl install -B SAM
]]>
</screen>
</para>
<section id='sam.installation.prerequisites'>
<title>Prerequisites</title>
<para>
@ -53,11 +76,11 @@
<section id='sam.installation.linux'>
<title>Linux installation steps</title>
<para>
The sam extension is supplied as a PECL module, which
you should be able to download and install in one step as follows:
<screen>
<![CDATA[
pear install sam
The sam extension is supplied as a PECL module, which
you should be able to download and install in one step as follows:
<screen>
<![CDATA[
pecl install sam
]]>
</screen>
(Depending on your php environment, you will probably need to be root
@ -70,11 +93,18 @@ pear install sam
<![CDATA[
extension=sam.so
]]>
</screen>
</screen>
If you intend to use the XMS support to access the IBM Messaging and Queuing family
you must also enable the SAM XMS extension.
<screen>
<![CDATA[
extension=sam_xms.so
]]>
</screen>
</para>
<para>
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:
<screen>
<![CDATA[
pear download sam #downloads sam-<version>.tgz
@ -95,13 +125,13 @@ make install #you may need to be root for this step
<section id='sam.installation.windows'>
<title>Windows installation steps</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
@ -131,9 +161,9 @@ c:\php-build\-
Windows Platform SDK which again can be downloaded from the Microsoft web site.
</para>
<para>
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.
</para>
<para>
To build the extension open a build environment window by going to the
@ -157,32 +187,67 @@ set PATH=..\win32build\bin;%PATH%
]]>
</screen>
</para>
<para>
<para>
Run the buildconf.bat command. This should rebuild the configure.js
file.
</para>
<para>
Run the cscript command:
<screen>
<![CDATA[
cscript /nologo configure.js --with-sam="c:\program files\ibm\xms"
Run the cscript command with the appropriate options. To build just the
SAM extension framework and MQTT support use:
<screen>
<![CDATA[
cscript /nologo configure.js --with-sam
]]>
</screen>
To build the SAM framework and the XMS support use:
<screen>
<![CDATA[
cscript /nologo configure.js --with-sam --with-sam_xms="c:\program files\ibm\xms"
]]>
</screen>
</para>
<para>
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.
</para>
<para>
You can specify whatever other cscript parameters you require to
include or exclude items from the php build or select options.
</para>
<para>
Assuming all has gone well so far you can now finally run a make!
<screen>
<![CDATA[
Assuming all has gone well so far you can now finally run a make for the SAM framework!
<screen>
<![CDATA[
nmake php_sam.dll
]]>
</screen>
Also if you are using the XMS support you must make the sam_xms extensions:
<screen>
<![CDATA[
nmake php_sam_xms.dll
]]>
</screen>
</para>
<para>
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.
</para>
<para>
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;
:
<screen>
<![CDATA[
extension=php_sam.dll
]]>
</screen>
If you intend to use the XMS support to access the IBM Messgaing and Queuing family
you must also enable the SAM XMS extension.
<screen>
<![CDATA[
extension=php_sam_xms.dll
]]>
</screen>
</para>
@ -195,24 +260,66 @@ nmake php_sam.dll
process to ensure the <filename>php_sam.dll</filename> 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
<filename>php_sam.dll</filename> has been generated (usually
<filename>php_sam.dll</filename> has been generated (usually
Release_TS or Debug_TS below the php source directory) and issue the
following magic incantation:
<screen>
<![CDATA[
mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2
]]>
</screen>
</screen>
If you are using the XMS capabilities you will need to do the same with the
SAM XMS DLL:
<screen>
<![CDATA[
mt.exe -manifest php_sam_xms.dll.manifest -outputresource:php_sam_xms.dll;2
]]>
</screen>
</para>
<para>
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
<ulink url="&url.ms.crt;">runtime package</ulink>.
</para>
</section>
<section id='sam.installation.configutaion'>
<title>Protocol support and mapping</title>
<para>
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.
</para>
<para>
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:
<screen>
<![CDATA[
[sam]
sam.factory.mqtt=mqtt
sam.factory.wmq=xms
sam.factory.wmq:client=xms
sam.factory.wmq:bindings=xms
sam.factory.wpm=xms
sam.factory.wrtt=xms
]]>
</screen>
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.
</para>
<para>
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.
</para>
</section>
</section> <!-- id=sam.installation -->
<section id='sam.usage'>
@ -240,10 +347,10 @@ mt.exe -manifest php_sam.dll.manifest -outputresource:php_sam.dll;2
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->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'));
?>
]]>
</programlisting>
@ -255,15 +362,29 @@ $conn->connect(SAM_WMQ, array(SAM_HOST => myhost.mycompany.com,
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->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'));
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Creating a connection and connecting to an MQTT server</title>
<programlisting role='php'>
<![CDATA[
<?php
$conn = new SAMConnection();
$conn->connect(SAM_MQTT, array(SAM_HOST => 'myhost.mycompany.com',
SAM_PORT => 1883));
?>
]]>
</programlisting>
</example>
</para>
</section> <!-- id=sam.connections -->
<section id='sam.messages'>
@ -386,8 +507,8 @@ if (!$correlid) {
otherwise identical to the point to point model.
</para>
<para>
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) {
<para>
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.
</para>
<para>
@ -490,7 +611,7 @@ if (!$conn->unsubscribe($subName)) {
<title>Error handling</title>
<para>
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) {
<listitem>
<para>
<link linkend='function.samconnection-peekall'>peekAll</link>
- 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.
</para>
</listitem>
</listitem>
<listitem>
<para>
<link linkend='function.samconnection-receive'>receive</link>
@ -621,6 +742,12 @@ if (!$correlid) {
- a method that sends a message to a queue or posts to a topic
</para>
</listitem>
<listitem>
<para>
<link linkend='function.samconnection-setDebug'>setDebug</link>
- a method that switches additional debugging output on or off
</para>
</listitem>
<listitem>
<para>
<link linkend='function.samconnection-subscribe'>subscribe</link>