From 9eb1e8a12aba34e9d5accb62b67ca67795044447 Mon Sep 17 00:00:00 2001
From: Sara Golemon <pollita@php.net>
Date: Thu, 30 Dec 2004 05:09:31 +0000
Subject: [PATCH] Additional Documentation: ssh2_shell(),
 ssh2_methods_negotiated(), and ssh2_tunnel()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@175985 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../functions/ssh2-methods-negotiated.xml     | 40 ++++++++++++++++--
 reference/ssh2/functions/ssh2-shell.xml       | 41 +++++++++++++++++--
 reference/ssh2/functions/ssh2-tunnel.xml      | 27 ++++++++++--
 3 files changed, 97 insertions(+), 11 deletions(-)

diff --git a/reference/ssh2/functions/ssh2-methods-negotiated.xml b/reference/ssh2/functions/ssh2-methods-negotiated.xml
index 3f25b0c1e3..42f2d907a8 100644
--- a/reference/ssh2/functions/ssh2-methods-negotiated.xml
+++ b/reference/ssh2/functions/ssh2-methods-negotiated.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-methods-negotiated">
    <refnamediv>
@@ -15,9 +15,41 @@
      <methodparam><type>resource</type><parameter>session</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Return list of negotiaed methods
-    </para>
+    <simpara>
+     Returns list of negotiaed methods.
+    </simpara>
+
+    <example>
+     <title>Determining what methods were negotiated</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+$methods = ssh2_methods_negotiated($connection);
+
+echo "Encryption keys were negotiated using: {$methods['kex']}\n";
+echo "Server identified using an {$methods['hostkey']} with ";
+echo "fingerprint: " . ssh2_fingerprint($connection) . "\n";
+
+echo "Client to Server packets will use methods:\n";
+echo "\tCrypt: {$method['client_to_server']['crypt']}\n";
+echo "\tComp: {$method['client_to_server']['comp']}\n";
+echo "\tMAC: {$method['client_to_server']['mac']}\n";
+
+echo "Server to Client packets will use methods:\n";
+echo "\tCrypt: {$method['server_to_client']['crypt']}\n";
+echo "\tComp: {$method['server_to_client']['comp']}\n";
+echo "\tMAC: {$method['server_to_client']['mac']}\n";
+
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>ssh2_connect</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-shell.xml b/reference/ssh2/functions/ssh2-shell.xml
index afe9b81db2..064faefc7c 100644
--- a/reference/ssh2/functions/ssh2-shell.xml
+++ b/reference/ssh2/functions/ssh2-shell.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-shell">
    <refnamediv>
@@ -20,9 +20,42 @@
      <methodparam choice="opt"><type>int</type><parameter>width_height_type</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Open a shell at the remote end and allocate a stream for it
-    </para>
+    <simpara>
+     Open a shell at the remote end and allocate a stream for it.
+     <parameter>term_type</parameter> should correspond to one of the entries
+     in the target system's <literal>/etc/termcap</literal> file and defaults to <literal>vanilla</literal>.
+     <parameter>env</parameter> may be passed as an associative array of name/value pairs
+     to set in the target environment.
+    </simpara>
+
+    <simpara>
+     <parameter>width</parameter>, and <parameter>height</parameter>
+     define the width and height of the virtual terminal allocated for the shell process.
+     <parameter>width_height_type</parameter> should be one of
+     <constant>SSH2_TERM_UNIT_CHARS</constant> or
+     <constant>SSH2_TERM_UNIT_PIXELS</constant>.
+    </simpara>
+
+    <example>
+     <title>Executing a command</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+
+$stream = ssh2_shell($connection, 'vt102', 80, 24, SSH2_TERM_UNIT_CHARS);
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>ssh2_exec</function>,
+     <function>ssh2_tunnel</function>, and
+     <function>ssh2_fetch_stream</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-tunnel.xml b/reference/ssh2/functions/ssh2-tunnel.xml
index fad1c230da..ecb1b6df2c 100644
--- a/reference/ssh2/functions/ssh2-tunnel.xml
+++ b/reference/ssh2/functions/ssh2-tunnel.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-tunnel">
    <refnamediv>
@@ -17,10 +17,31 @@
      <methodparam><type>int</type><parameter>port</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
+    <simpara>
      Open a socket stream to an arbitrary host/port by way of the
      currently connected SSH server.
-    </para>
+    </simpara>
+
+    <example>
+     <title>Opening a tunnel to an arbitrary host</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_pubkey_file($connection, 'username', 'id_dsa.pub', 'id_dsa');
+
+$tunnel = ssh2_tunnel($connection, '10.0.0.101', 12345);
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>ssh2_connect</function>, and
+     <function>fsockopen</function>
+    </simpara>
 
    </refsect1>
   </refentry>