From d10205057eb865145c5f0c7395127058ecd288fa Mon Sep 17 00:00:00 2001
From: Arvid Norberg <arvid@libtorrent.org>
Date: Sun, 6 Apr 2008 23:18:35 +0000
Subject: [PATCH] port mapping update

---
 docs/manual.html                         | 260 +++++++++++++++++------
 docs/manual.rst                          | 124 ++++++++++-
 include/libtorrent/alert_types.hpp       |  10 +-
 include/libtorrent/aux_/session_impl.hpp |   4 +-
 include/libtorrent/session.hpp           |   6 +-
 include/libtorrent/upnp.hpp              |   4 +-
 src/session.cpp                          |   4 +-
 src/session_impl.cpp                     |  22 +-
 8 files changed, 339 insertions(+), 95 deletions(-)

diff --git a/docs/manual.html b/docs/manual.html
index fc4c753bc..c9d6a2aea 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -128,81 +128,87 @@
 <li><a class="reference internal" href="#big-number" id="id109">big_number</a></li>
 <li><a class="reference internal" href="#hasher" id="id110">hasher</a></li>
 <li><a class="reference internal" href="#fingerprint" id="id111">fingerprint</a></li>
-<li><a class="reference internal" href="#free-functions" id="id112">free functions</a><ul>
-<li><a class="reference internal" href="#identify-client" id="id113">identify_client()</a></li>
-<li><a class="reference internal" href="#client-fingerprint" id="id114">client_fingerprint()</a></li>
-<li><a class="reference internal" href="#bdecode-bencode" id="id115">bdecode() bencode()</a></li>
-<li><a class="reference internal" href="#supports-sparse-files" id="id116">supports_sparse_files()</a></li>
+<li><a class="reference internal" href="#upnp-and-nat-pmp" id="id112">UPnP and NAT-PMP</a><ul>
+<li><a class="reference internal" href="#add-mapping" id="id113">add_mapping</a></li>
+<li><a class="reference internal" href="#delete-mapping" id="id114">delete_mapping</a></li>
+<li><a class="reference internal" href="#router-model" id="id115">router_model()</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#alerts" id="id117">alerts</a><ul>
-<li><a class="reference internal" href="#external-ip-alert" id="id118">external_ip_alert</a></li>
-<li><a class="reference internal" href="#listen-failed-alert" id="id119">listen_failed_alert</a></li>
-<li><a class="reference internal" href="#portmap-error-alert" id="id120">portmap_error_alert</a></li>
-<li><a class="reference internal" href="#portmap-alert" id="id121">portmap_alert</a></li>
-<li><a class="reference internal" href="#file-error-alert" id="id122">file_error_alert</a></li>
-<li><a class="reference internal" href="#tracker-announce-alert" id="id123">tracker_announce_alert</a></li>
-<li><a class="reference internal" href="#tracker-alert" id="id124">tracker_alert</a></li>
-<li><a class="reference internal" href="#tracker-reply-alert" id="id125">tracker_reply_alert</a></li>
-<li><a class="reference internal" href="#tracker-warning-alert" id="id126">tracker_warning_alert</a></li>
-<li><a class="reference internal" href="#scrape-reply-alert" id="id127">scrape_reply_alert</a></li>
-<li><a class="reference internal" href="#scrape-failed-alert" id="id128">scrape_failed_alert</a></li>
-<li><a class="reference internal" href="#url-seed-alert" id="id129">url_seed_alert</a></li>
-<li><a class="reference internal" href="#hash-failed-alert" id="id130">hash_failed_alert</a></li>
-<li><a class="reference internal" href="#peer-ban-alert" id="id131">peer_ban_alert</a></li>
-<li><a class="reference internal" href="#peer-error-alert" id="id132">peer_error_alert</a></li>
-<li><a class="reference internal" href="#invalid-request-alert" id="id133">invalid_request_alert</a></li>
-<li><a class="reference internal" href="#torrent-finished-alert" id="id134">torrent_finished_alert</a></li>
-<li><a class="reference internal" href="#metadata-failed-alert" id="id135">metadata_failed_alert</a></li>
-<li><a class="reference internal" href="#metadata-received-alert" id="id136">metadata_received_alert</a></li>
-<li><a class="reference internal" href="#fastresume-rejected-alert" id="id137">fastresume_rejected_alert</a></li>
-<li><a class="reference internal" href="#peer-blocked-alert" id="id138">peer_blocked_alert</a></li>
-<li><a class="reference internal" href="#storage-moved-alert" id="id139">storage_moved_alert</a></li>
-<li><a class="reference internal" href="#torrent-paused-alert" id="id140">torrent_paused_alert</a></li>
-<li><a class="reference internal" href="#dispatcher" id="id141">dispatcher</a></li>
+<li><a class="reference internal" href="#free-functions" id="id116">free functions</a><ul>
+<li><a class="reference internal" href="#identify-client" id="id117">identify_client()</a></li>
+<li><a class="reference internal" href="#client-fingerprint" id="id118">client_fingerprint()</a></li>
+<li><a class="reference internal" href="#bdecode-bencode" id="id119">bdecode() bencode()</a></li>
+<li><a class="reference internal" href="#supports-sparse-files" id="id120">supports_sparse_files()</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#exceptions" id="id142">exceptions</a><ul>
-<li><a class="reference internal" href="#invalid-handle" id="id143">invalid_handle</a></li>
-<li><a class="reference internal" href="#duplicate-torrent" id="id144">duplicate_torrent</a></li>
-<li><a class="reference internal" href="#invalid-encoding" id="id145">invalid_encoding</a></li>
-<li><a class="reference internal" href="#type-error" id="id146">type_error</a></li>
-<li><a class="reference internal" href="#invalid-torrent-file" id="id147">invalid_torrent_file</a></li>
+<li><a class="reference internal" href="#alerts" id="id121">alerts</a><ul>
+<li><a class="reference internal" href="#external-ip-alert" id="id122">external_ip_alert</a></li>
+<li><a class="reference internal" href="#listen-failed-alert" id="id123">listen_failed_alert</a></li>
+<li><a class="reference internal" href="#portmap-error-alert" id="id124">portmap_error_alert</a></li>
+<li><a class="reference internal" href="#portmap-alert" id="id125">portmap_alert</a></li>
+<li><a class="reference internal" href="#file-error-alert" id="id126">file_error_alert</a></li>
+<li><a class="reference internal" href="#tracker-announce-alert" id="id127">tracker_announce_alert</a></li>
+<li><a class="reference internal" href="#tracker-alert" id="id128">tracker_alert</a></li>
+<li><a class="reference internal" href="#tracker-reply-alert" id="id129">tracker_reply_alert</a></li>
+<li><a class="reference internal" href="#tracker-warning-alert" id="id130">tracker_warning_alert</a></li>
+<li><a class="reference internal" href="#scrape-reply-alert" id="id131">scrape_reply_alert</a></li>
+<li><a class="reference internal" href="#scrape-failed-alert" id="id132">scrape_failed_alert</a></li>
+<li><a class="reference internal" href="#url-seed-alert" id="id133">url_seed_alert</a></li>
+<li><a class="reference internal" href="#hash-failed-alert" id="id134">hash_failed_alert</a></li>
+<li><a class="reference internal" href="#peer-ban-alert" id="id135">peer_ban_alert</a></li>
+<li><a class="reference internal" href="#peer-error-alert" id="id136">peer_error_alert</a></li>
+<li><a class="reference internal" href="#invalid-request-alert" id="id137">invalid_request_alert</a></li>
+<li><a class="reference internal" href="#torrent-finished-alert" id="id138">torrent_finished_alert</a></li>
+<li><a class="reference internal" href="#metadata-failed-alert" id="id139">metadata_failed_alert</a></li>
+<li><a class="reference internal" href="#metadata-received-alert" id="id140">metadata_received_alert</a></li>
+<li><a class="reference internal" href="#fastresume-rejected-alert" id="id141">fastresume_rejected_alert</a></li>
+<li><a class="reference internal" href="#peer-blocked-alert" id="id142">peer_blocked_alert</a></li>
+<li><a class="reference internal" href="#storage-moved-alert" id="id143">storage_moved_alert</a></li>
+<li><a class="reference internal" href="#torrent-paused-alert" id="id144">torrent_paused_alert</a></li>
+<li><a class="reference internal" href="#dispatcher" id="id145">dispatcher</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#storage-interface" id="id148">storage_interface</a><ul>
-<li><a class="reference internal" href="#initialize" id="id149">initialize()</a></li>
-<li><a class="reference internal" href="#read" id="id150">read()</a></li>
-<li><a class="reference internal" href="#write" id="id151">write()</a></li>
-<li><a class="reference internal" href="#id11" id="id152">move_storage()</a></li>
-<li><a class="reference internal" href="#verify-resume-data" id="id153">verify_resume_data()</a></li>
-<li><a class="reference internal" href="#id12" id="id154">write_resume_data( )</a></li>
-<li><a class="reference internal" href="#move-slot" id="id155">move_slot()</a></li>
-<li><a class="reference internal" href="#swap-slots" id="id156">swap_slots()</a></li>
-<li><a class="reference internal" href="#swap-slots3" id="id157">swap_slots3()</a></li>
-<li><a class="reference internal" href="#hash-for-slot" id="id158">hash_for_slot()</a></li>
-<li><a class="reference internal" href="#release-files" id="id159">release_files()</a></li>
-<li><a class="reference internal" href="#delete-files" id="id160">delete_files()</a></li>
+<li><a class="reference internal" href="#exceptions" id="id146">exceptions</a><ul>
+<li><a class="reference internal" href="#invalid-handle" id="id147">invalid_handle</a></li>
+<li><a class="reference internal" href="#duplicate-torrent" id="id148">duplicate_torrent</a></li>
+<li><a class="reference internal" href="#invalid-encoding" id="id149">invalid_encoding</a></li>
+<li><a class="reference internal" href="#type-error" id="id150">type_error</a></li>
+<li><a class="reference internal" href="#invalid-torrent-file" id="id151">invalid_torrent_file</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#fast-resume" id="id161">fast resume</a><ul>
-<li><a class="reference internal" href="#file-format" id="id162">file format</a></li>
+<li><a class="reference internal" href="#storage-interface" id="id152">storage_interface</a><ul>
+<li><a class="reference internal" href="#initialize" id="id153">initialize()</a></li>
+<li><a class="reference internal" href="#read" id="id154">read()</a></li>
+<li><a class="reference internal" href="#write" id="id155">write()</a></li>
+<li><a class="reference internal" href="#id11" id="id156">move_storage()</a></li>
+<li><a class="reference internal" href="#verify-resume-data" id="id157">verify_resume_data()</a></li>
+<li><a class="reference internal" href="#id12" id="id158">write_resume_data( )</a></li>
+<li><a class="reference internal" href="#move-slot" id="id159">move_slot()</a></li>
+<li><a class="reference internal" href="#swap-slots" id="id160">swap_slots()</a></li>
+<li><a class="reference internal" href="#swap-slots3" id="id161">swap_slots3()</a></li>
+<li><a class="reference internal" href="#hash-for-slot" id="id162">hash_for_slot()</a></li>
+<li><a class="reference internal" href="#release-files" id="id163">release_files()</a></li>
+<li><a class="reference internal" href="#delete-files" id="id164">delete_files()</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#threads" id="id163">threads</a></li>
-<li><a class="reference internal" href="#storage-allocation" id="id164">storage allocation</a><ul>
-<li><a class="reference internal" href="#sparse-allocation" id="id165">sparse allocation</a></li>
-<li><a class="reference internal" href="#full-allocation" id="id166">full allocation</a></li>
-<li><a class="reference internal" href="#compact-allocation" id="id167">compact allocation</a></li>
+<li><a class="reference internal" href="#fast-resume" id="id165">fast resume</a><ul>
+<li><a class="reference internal" href="#file-format" id="id166">file format</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#extensions" id="id168">extensions</a><ul>
-<li><a class="reference internal" href="#metadata-from-peers" id="id169">metadata from peers</a></li>
-<li><a class="reference internal" href="#http-seeding" id="id170">HTTP seeding</a></li>
+<li><a class="reference internal" href="#threads" id="id167">threads</a></li>
+<li><a class="reference internal" href="#storage-allocation" id="id168">storage allocation</a><ul>
+<li><a class="reference internal" href="#sparse-allocation" id="id169">sparse allocation</a></li>
+<li><a class="reference internal" href="#full-allocation" id="id170">full allocation</a></li>
+<li><a class="reference internal" href="#compact-allocation" id="id171">compact allocation</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#filename-checks" id="id171">filename checks</a></li>
-<li><a class="reference internal" href="#acknowledgments" id="id172">acknowledgments</a></li>
+<li><a class="reference internal" href="#extensions" id="id172">extensions</a><ul>
+<li><a class="reference internal" href="#metadata-from-peers" id="id173">metadata from peers</a></li>
+<li><a class="reference internal" href="#http-seeding" id="id174">HTTP seeding</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#filename-checks" id="id175">filename checks</a></li>
+<li><a class="reference internal" href="#acknowledgments" id="id176">acknowledgments</a></li>
 </ul>
 </div>
 <div class="section" id="overview">
@@ -213,6 +219,8 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 <ul>
 <li><p class="first">construct a session</p>
 </li>
+<li><p class="first">start DHT, LSD, UPnP, NAT-PMP etc (see <a href="#id177"><span class="problematic" id="id178">start_dht_</span></a>, <a href="#id179"><span class="problematic" id="id180">start_lsd_</span></a>, <a href="#id181"><span class="problematic" id="id182">start_upnp_</span></a> and <a href="#id183"><span class="problematic" id="id184">start_natpmp_</span></a>)</p>
+</li>
 <li><p class="first">parse .torrent-files and add them to the session (see <a class="reference internal" href="#bdecode-bencode">bdecode() bencode()</a> and <a class="reference internal" href="#add-torrent">add_torrent()</a>)</p>
 </li>
 <li><p class="first">main loop (see <a class="reference internal" href="#session">session</a>)</p>
@@ -359,10 +367,10 @@ class session: public boost::noncopyable
         void start_lsd();
         void stop_lsd();
 
-        boost::intrusive_ptr&lt;upnp&gt; start_upnp();
+        upnp* start_upnp();
         void stop_upnp();
 
-        boost::intrusvice_ptr&lt;natpmp&gt; start_natpmp();
+        natpmp* start_natpmp();
         void stop_natpmp();
 };
 </pre>
@@ -1003,24 +1011,32 @@ look for peers on the same swarm within multicast reach.</p>
 <h2>start_upnp() stop_upnp()</h2>
 <blockquote>
 <pre class="literal-block">
-boost::intrusive_ptr&lt;upnp&gt; start_upnp();
+upnp* start_upnp();
 void stop_upnp();
 </pre>
 </blockquote>
 <p>Starts and stops the UPnP service. When started, the listen port and the DHT
 port are attempted to be forwarded on local UPnP router devices.</p>
+<p>The upnp object returned by <tt class="docutils literal"><span class="pre">start_upnp()</span></tt> can be used to add and remove
+arbitrary port mappings. Mapping status is returned through the
+<a class="reference internal" href="#portmap-alert">portmap_alert</a> and the <a class="reference internal" href="#portmap-error-alert">portmap_error_alert</a>. The object will be valid until
+<a href="#id185"><span class="problematic" id="id186">stop_upnp_</span></a> is called. See <a class="reference internal" href="#upnp-and-nat-pmp">UPnP and NAT-PMP</a>.</p>
 <p>It is off by default.</p>
 </div>
 <div class="section" id="start-natpmp-stop-natpmp">
 <h2>start_natpmp() stop_natpmp()</h2>
 <blockquote>
 <pre class="literal-block">
-boost::intrusvice_ptr&lt;natpmp&gt; start_natpmp();
+natpmp* start_natpmp();
 void stop_natpmp();
 </pre>
 </blockquote>
 <p>Starts and stops the NAT-PMP service. When started, the listen port and the DHT
 port are attempted to be forwarded on the router through NAT-PMP.</p>
+<p>The natpmp object returned by <tt class="docutils literal"><span class="pre">start_natpmp()</span></tt> can be used to add and remove
+arbitrary port mappings. Mapping status is returned through the
+<a class="reference internal" href="#portmap-alert">portmap_alert</a> and the <a class="reference internal" href="#portmap-error-alert">portmap_error_alert</a>. The object will be valid until
+<a href="#id187"><span class="problematic" id="id188">stop_upnp_</span></a> is called. See <a class="reference internal" href="#upnp-and-nat-pmp">UPnP and NAT-PMP</a>.</p>
 <p>It is off by default.</p>
 </div>
 </div>
@@ -3195,6 +3211,83 @@ sure not to clash with anybody else. Here are some taken id's:</p>
 version of your client. All these numbers must be within the range [0, 9].</p>
 <p><tt class="docutils literal"><span class="pre">to_string()</span></tt> will generate the actual string put in the peer-id, and return it.</p>
 </div>
+<div class="section" id="upnp-and-nat-pmp">
+<h1>UPnP and NAT-PMP</h1>
+<p>The <tt class="docutils literal"><span class="pre">upnp</span></tt> and <tt class="docutils literal"><span class="pre">natpmp</span></tt> classes contains the state for all UPnP and NAT-PMP mappings,
+by default 1 or two mappings are made by libtorrent, one for the listen port and one
+for the DHT port (UDP).</p>
+<pre class="literal-block">
+class upnp
+{
+public:
+
+        enum protocol_type { none = 0, udp = 1, tcp = 2 };
+        int add_mapping(protocol_type p, int external_port, int local_port);
+        void delete_mapping(int mapping_index);
+
+        void discover_device();
+        void close();
+
+        std::string router_model();
+};
+
+class natpmp
+{
+public:
+
+        enum protocol_type { none = 0, udp = 1, tcp = 2 };
+        int add_mapping(protocol_type p, int external_port, int local_port);
+        void delete_mapping(int mapping_index);
+
+        void close();
+        void rebind(address const&amp; listen_interface);
+};
+</pre>
+<p><tt class="docutils literal"><span class="pre">discover_device()</span></tt>, <tt class="docutils literal"><span class="pre">close()</span></tt> and <tt class="docutils literal"><span class="pre">rebind()</span></tt> are for internal uses and should
+not be called directly by clients.</p>
+<div class="section" id="add-mapping">
+<h2>add_mapping</h2>
+<blockquote>
+<pre class="literal-block">
+int add_mapping(protocol_type p, int external_port, int local_port);
+</pre>
+</blockquote>
+<p>Attempts to add a port mapping for the specified protocol. Valid protocols are
+<tt class="docutils literal"><span class="pre">upnp::tcp</span></tt> and <tt class="docutils literal"><span class="pre">upnp::udp</span></tt> for the UPnP class and <tt class="docutils literal"><span class="pre">natpmp::tcp</span></tt> and
+<tt class="docutils literal"><span class="pre">natpmp::udp</span></tt> for the NAT-PMP class.</p>
+<p><tt class="docutils literal"><span class="pre">external_port</span></tt> is the port on the external address that will be mapped. This
+is a hint, you are not guaranteed that this port will be available, and it may
+end up being something else. In the <a class="reference internal" href="#portmap-alert">portmap_alert</a> notification, the actual
+external port is reported.</p>
+<p><tt class="docutils literal"><span class="pre">local_port</span></tt> is the port in the local machine that the mapping should forward
+to.</p>
+<p>The return value is an index that identifies this port mapping. This is used
+to refer to mappings that fails or succeeds in the <a class="reference internal" href="#portmap-error-alert">portmap_error_alert</a> and
+<a class="reference internal" href="#portmap-alert">portmap_alert</a> respectively. If The mapping fails immediately, the return value
+is -1, which means failure. There will not be any error alert notification for
+mappings that fail with a -1 return value.</p>
+</div>
+<div class="section" id="delete-mapping">
+<h2>delete_mapping</h2>
+<blockquote>
+<pre class="literal-block">
+void delete_mapping(int mapping_index);
+</pre>
+</blockquote>
+<p>This function removes a port mapping. <tt class="docutils literal"><span class="pre">mapping_index</span></tt> is the index that refers
+to the mapping you want to remove, which was returned from <a class="reference internal" href="#add-mapping">add_mapping</a>.</p>
+</div>
+<div class="section" id="router-model">
+<h2>router_model()</h2>
+<blockquote>
+<pre class="literal-block">
+std::string router_model();
+</pre>
+</blockquote>
+<p>This is only available for UPnP routers. If the model is advertized by
+the router, it can be queried through this function.</p>
+</div>
+</div>
 <div class="section" id="free-functions">
 <h1>free functions</h1>
 <div class="section" id="identify-client">
@@ -3406,10 +3499,15 @@ appears there is no NAT router that can be remote controlled to add port
 mappings.</p>
 <p>The alert is generated as severity <tt class="docutils literal"><span class="pre">warning</span></tt>, since it should be displayed
 to the user somehow, and could mean reduced preformance.</p>
+<p><tt class="docutils literal"><span class="pre">mapping</span></tt> refers to the mapping index of the port map that failed, i.e.
+the index returned from <a class="reference internal" href="#add-mapping">add_mapping</a>.</p>
+<p><tt class="docutils literal"><span class="pre">type</span></tt> is 0 for NAT-PMP and 1 for UPnP.</p>
 <pre class="literal-block">
 struct portmap_error_alert: alert
 {
-        portmap_error_alert(const std::string&amp; msg);
+        portmap_error_alert(int mapping, int type, const std::string&amp; msg);
+        int mapping;
+        int type;
         virtual std::auto_ptr&lt;alert&gt; clone() const;
 };
 </pre>
@@ -3421,10 +3519,17 @@ a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP
 capable router, this is typically generated once when mapping the TCP
 port and, if DHT is enabled, when the UDP port is mapped. This is merely
 an informational alert, and is generated at severity level <tt class="docutils literal"><span class="pre">info</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">mapping</span></tt> refers to the mapping index of the port map that failed, i.e.
+the index returned from <a class="reference internal" href="#add-mapping">add_mapping</a>.</p>
+<p><tt class="docutils literal"><span class="pre">external_port</span></tt> is the external port allocated for the mapping.</p>
+<p><tt class="docutils literal"><span class="pre">type</span></tt> is 0 for NAT-PMP and 1 for UPnP.</p>
 <pre class="literal-block">
 struct portmap_alert: alert
 {
-        portmap_alert(const std::string&amp; msg);
+        portmap_alert(int mapping, int port, int type, const std::string&amp; msg);
+        int mapping;
+        int external_port;
+        int type;
         virtual std::auto_ptr&lt;alert&gt; clone() const;
 };
 </pre>
@@ -4456,6 +4561,27 @@ scripts.</p>
 <p>Project is hosted by sourceforge.</p>
 <p><a class="reference external" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
 </div>
+<div class="system-messages section">
+<h1>Docutils System Messages</h1>
+<div class="system-message" id="id177">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 21); <em><a href="#id178">backlink</a></em></p>
+Unknown target name: &quot;start_dht&quot;.</div>
+<div class="system-message" id="id179">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 21); <em><a href="#id180">backlink</a></em></p>
+Unknown target name: &quot;start_lsd&quot;.</div>
+<div class="system-message" id="id181">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 21); <em><a href="#id182">backlink</a></em></p>
+Unknown target name: &quot;start_upnp&quot;.</div>
+<div class="system-message" id="id183">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 21); <em><a href="#id184">backlink</a></em></p>
+Unknown target name: &quot;start_natpmp&quot;.</div>
+<div class="system-message" id="id185">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 893); <em><a href="#id186">backlink</a></em></p>
+Unknown target name: &quot;stop_upnp&quot;.</div>
+<div class="system-message" id="id187">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 911); <em><a href="#id188">backlink</a></em></p>
+Unknown target name: &quot;stop_upnp&quot;.</div>
+</div>
 </div>
 </body>
 </html>
diff --git a/docs/manual.rst b/docs/manual.rst
index 2482be904..5f22f6961 100644
--- a/docs/manual.rst
+++ b/docs/manual.rst
@@ -18,6 +18,7 @@ the ``session``, it contains the main loop that serves all torrents.
 The basic usage is as follows:
 
 * construct a session
+* start DHT, LSD, UPnP, NAT-PMP etc (see start_dht_, start_lsd_, start_upnp_ and start_natpmp_)
 * parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `add_torrent()`_)
 * main loop (see session_)
 
@@ -165,10 +166,10 @@ The ``session`` class has the following synopsis::
 		void start_lsd();
 		void stop_lsd();
 
-		boost::intrusive_ptr<upnp> start_upnp();
+		upnp* start_upnp();
 		void stop_upnp();
 
-		boost::intrusvice_ptr<natpmp> start_natpmp();
+		natpmp* start_natpmp();
 		void stop_natpmp();
 	};
 
@@ -883,12 +884,17 @@ start_upnp() stop_upnp()
 
 	::
 	
-		boost::intrusive_ptr<upnp> start_upnp();
+		upnp* start_upnp();
 		void stop_upnp();
 
 Starts and stops the UPnP service. When started, the listen port and the DHT
 port are attempted to be forwarded on local UPnP router devices.
 
+The upnp object returned by ``start_upnp()`` can be used to add and remove
+arbitrary port mappings. Mapping status is returned through the
+portmap_alert_ and the portmap_error_alert_. The object will be valid until
+stop_upnp_ is called. See `UPnP and NAT-PMP`_.
+
 It is off by default.
 
 start_natpmp() stop_natpmp()
@@ -896,12 +902,17 @@ start_natpmp() stop_natpmp()
 
 	::
 		
-		boost::intrusvice_ptr<natpmp> start_natpmp();
+		natpmp* start_natpmp();
 		void stop_natpmp();
 
 Starts and stops the NAT-PMP service. When started, the listen port and the DHT
 port are attempted to be forwarded on the router through NAT-PMP.
 
+The natpmp object returned by ``start_natpmp()`` can be used to add and remove
+arbitrary port mappings. Mapping status is returned through the
+portmap_alert_ and the portmap_error_alert_. The object will be valid until
+stop_upnp_ is called. See `UPnP and NAT-PMP`_.
+
 It is off by default.
 
 
@@ -3257,6 +3268,90 @@ version of your client. All these numbers must be within the range [0, 9].
 ``to_string()`` will generate the actual string put in the peer-id, and return it.
 
 
+UPnP and NAT-PMP
+================
+
+The ``upnp`` and ``natpmp`` classes contains the state for all UPnP and NAT-PMP mappings,
+by default 1 or two mappings are made by libtorrent, one for the listen port and one
+for the DHT port (UDP).
+
+::
+
+	class upnp
+	{
+	public:
+
+		enum protocol_type { none = 0, udp = 1, tcp = 2 };
+		int add_mapping(protocol_type p, int external_port, int local_port);
+		void delete_mapping(int mapping_index);
+	
+		void discover_device();
+		void close();
+	
+		std::string router_model();
+	};
+
+	class natpmp
+	{
+	public:
+	
+		enum protocol_type { none = 0, udp = 1, tcp = 2 };
+		int add_mapping(protocol_type p, int external_port, int local_port);
+		void delete_mapping(int mapping_index);
+	
+		void close();
+		void rebind(address const& listen_interface);
+	};
+
+``discover_device()``, ``close()`` and ``rebind()`` are for internal uses and should
+not be called directly by clients.
+
+add_mapping
+-----------
+
+	::
+
+		int add_mapping(protocol_type p, int external_port, int local_port);
+
+Attempts to add a port mapping for the specified protocol. Valid protocols are
+``upnp::tcp`` and ``upnp::udp`` for the UPnP class and ``natpmp::tcp`` and
+``natpmp::udp`` for the NAT-PMP class.
+
+``external_port`` is the port on the external address that will be mapped. This
+is a hint, you are not guaranteed that this port will be available, and it may
+end up being something else. In the portmap_alert_ notification, the actual
+external port is reported.
+
+``local_port`` is the port in the local machine that the mapping should forward
+to.
+
+The return value is an index that identifies this port mapping. This is used
+to refer to mappings that fails or succeeds in the portmap_error_alert_ and
+portmap_alert_ respectively. If The mapping fails immediately, the return value
+is -1, which means failure. There will not be any error alert notification for
+mappings that fail with a -1 return value.
+
+delete_mapping
+--------------
+
+	::
+
+		void delete_mapping(int mapping_index);
+
+This function removes a port mapping. ``mapping_index`` is the index that refers
+to the mapping you want to remove, which was returned from add_mapping_.
+
+router_model()
+--------------
+
+	::
+
+		std::string router_model();
+
+This is only available for UPnP routers. If the model is advertized by
+the router, it can be queried through this function.
+
+
 free functions
 ==============
 
@@ -3494,11 +3589,18 @@ mappings.
 The alert is generated as severity ``warning``, since it should be displayed
 to the user somehow, and could mean reduced preformance.
 
+``mapping`` refers to the mapping index of the port map that failed, i.e.
+the index returned from add_mapping_.
+
+``type`` is 0 for NAT-PMP and 1 for UPnP.
+
 ::
 
 	struct portmap_error_alert: alert
 	{
-		portmap_error_alert(const std::string& msg);
+		portmap_error_alert(int mapping, int type, const std::string& msg);
+		int mapping;
+		int type;
 		virtual std::auto_ptr<alert> clone() const;
 	};
 
@@ -3511,11 +3613,21 @@ capable router, this is typically generated once when mapping the TCP
 port and, if DHT is enabled, when the UDP port is mapped. This is merely
 an informational alert, and is generated at severity level ``info``.
 
+``mapping`` refers to the mapping index of the port map that failed, i.e.
+the index returned from add_mapping_.
+
+``external_port`` is the external port allocated for the mapping.
+
+``type`` is 0 for NAT-PMP and 1 for UPnP.
+
 ::
 
 	struct portmap_alert: alert
 	{
-		portmap_alert(const std::string& msg);
+		portmap_alert(int mapping, int port, int type, const std::string& msg);
+		int mapping;
+		int external_port;
+		int type;
 		virtual std::auto_ptr<alert> clone() const;
 	};
 
diff --git a/include/libtorrent/alert_types.hpp b/include/libtorrent/alert_types.hpp
index 6d24d0c2a..ef251d73a 100755
--- a/include/libtorrent/alert_types.hpp
+++ b/include/libtorrent/alert_types.hpp
@@ -426,11 +426,12 @@ namespace libtorrent
 
 	struct TORRENT_EXPORT portmap_error_alert: alert
 	{
-		portmap_error_alert(int i, const std::string& msg)
-			: mapping(i), alert(alert::warning, msg)
+		portmap_error_alert(int i, int t, const std::string& msg)
+			: alert(alert::warning, msg), mapping(i), type(t)
 		{}
 
 		int mapping;
+		int type;
 
 		virtual std::auto_ptr<alert> clone() const
 		{ return std::auto_ptr<alert>(new portmap_error_alert(*this)); }
@@ -438,12 +439,13 @@ namespace libtorrent
 
 	struct TORRENT_EXPORT portmap_alert: alert
 	{
-		portmap_alert(int i, int port, const std::string& msg)
-			: mapping(i), external_port(port), alert(alert::info, msg)
+		portmap_alert(int i, int port, int t, const std::string& msg)
+			: alert(alert::info, msg), mapping(i), external_port(port), type(t)
 		{}
 
 		int mapping;
 		int external_port;
+		int type;
 
 		virtual std::auto_ptr<alert> clone() const
 		{ return std::auto_ptr<alert>(new portmap_alert(*this)); }
diff --git a/include/libtorrent/aux_/session_impl.hpp b/include/libtorrent/aux_/session_impl.hpp
index c7db3bc5e..2bc4c9cef 100644
--- a/include/libtorrent/aux_/session_impl.hpp
+++ b/include/libtorrent/aux_/session_impl.hpp
@@ -320,8 +320,8 @@ namespace libtorrent
 			}
 #endif
 			void start_lsd();
-			boost::intrusive_ptr<natpmp> start_natpmp();
-			boost::intrusive_ptr<upnp> start_upnp();
+			natpmp* start_natpmp();
+			upnp* start_upnp();
 
 			void stop_lsd();
 			void stop_natpmp();
diff --git a/include/libtorrent/session.hpp b/include/libtorrent/session.hpp
index 369691e29..280c32a2b 100755
--- a/include/libtorrent/session.hpp
+++ b/include/libtorrent/session.hpp
@@ -76,6 +76,8 @@ namespace libtorrent
 	class ip_filter;
 	class port_filter;
 	class connection_queue;
+	class natpmp;
+	class upnp;
 
 	namespace fs = boost::filesystem;
 
@@ -284,8 +286,8 @@ namespace libtorrent
 		// starts/stops UPnP, NATPMP or LSD port mappers
 		// they are stopped by default
 		void start_lsd();
-		boost::intrusive_ptr<natpmp> start_natpmp();
-		boost::intrusive_ptr<upnp> start_upnp();
+		natpmp* start_natpmp();
+		upnp* start_upnp();
 
 		void stop_lsd();
 		void stop_natpmp();
diff --git a/include/libtorrent/upnp.hpp b/include/libtorrent/upnp.hpp
index de2b95714..7455fbf72 100644
--- a/include/libtorrent/upnp.hpp
+++ b/include/libtorrent/upnp.hpp
@@ -72,9 +72,9 @@ public:
 		, portmap_callback_t const& cb, bool ignore_nonrouters);
 	~upnp();
 
-	enum protocol_type { none = 0, tcp = 1, udp = 2 };
+	enum protocol_type { none = 0, udp = 1, tcp = 2 };
 	int add_mapping(protocol_type p, int external_port, int local_port);
-	void delete_mapping(int index);
+	void delete_mapping(int mapping_index);
 
 	void discover_device();
 	void close();
diff --git a/src/session.cpp b/src/session.cpp
index 603b1a9c2..c17a6602d 100755
--- a/src/session.cpp
+++ b/src/session.cpp
@@ -479,12 +479,12 @@ namespace libtorrent
 		m_impl->start_lsd();
 	}
 	
-	boost::intrusive_ptr<natpmp> session::start_natpmp()
+	natpmp* session::start_natpmp()
 	{
 		return m_impl->start_natpmp();
 	}
 	
-	boost::intrusive_ptr<upnp> session::start_upnp()
+	upnp* session::start_upnp()
 	{
 		return m_impl->start_upnp();
 	}
diff --git a/src/session_impl.cpp b/src/session_impl.cpp
index 0d10281de..8cebde580 100755
--- a/src/session_impl.cpp
+++ b/src/session_impl.cpp
@@ -1748,7 +1748,7 @@ namespace aux {
 			m_dht_settings.service_port = port;
 			if (m_alerts.should_post(alert::info))
 				m_alerts.post_alert(portmap_alert(mapping, port
-					, "successfully mapped UDP port"));
+					, map_transport, "successfully mapped UDP port"));
 			return;
 		}
 #endif
@@ -1759,19 +1759,21 @@ namespace aux {
 				m_listen_sockets.front().external_port = port;
 			if (m_alerts.should_post(alert::info))
 				m_alerts.post_alert(portmap_alert(mapping, port
-					, "successfully mapped TCP port"));
+					, map_transport, "successfully mapped TCP port"));
 			return;
 		}
 
 		if (!errmsg.empty())
 		{
 			if (m_alerts.should_post(alert::warning))
-				m_alerts.post_alert(portmap_error_alert(mapping, errmsg));
+				m_alerts.post_alert(portmap_error_alert(mapping
+					, map_transport, errmsg));
 		}
 		else
 		{
 			if (m_alerts.should_post(alert::warning))
-				m_alerts.post_alert(portmap_alert(mapping, port, "successfully mapped port"));
+				m_alerts.post_alert(portmap_alert(mapping, port
+					, map_transport, "successfully mapped port"));
 		}
 	}
 
@@ -2092,13 +2094,13 @@ namespace aux {
 			, bind(&session_impl::on_lsd_peer, this, _1, _2));
 	}
 	
-	boost::intrusive_ptr<natpmp> session_impl::start_natpmp()
+	natpmp* session_impl::start_natpmp()
 	{
 		mutex_t::scoped_lock l(m_mutex);
 
 		INVARIANT_CHECK;
 
-		if (m_natpmp) return m_natpmp;
+		if (m_natpmp) return m_natpmp.get();
 
 		m_natpmp = new natpmp(m_io_service
 			, m_listen_interface.address()
@@ -2113,16 +2115,16 @@ namespace aux {
 				, m_dht_settings.service_port 
 				, m_dht_settings.service_port);
 #endif
-		return m_natpmp;
+		return m_natpmp.get();
 	}
 
-	boost::intrusive_ptr<upnp> session_impl::start_upnp()
+	upnp* session_impl::start_upnp()
 	{
 		mutex_t::scoped_lock l(m_mutex);
 
 		INVARIANT_CHECK;
 
-		if (m_upnp) return m_upnp;
+		if (m_upnp) return m_upnp.get();
 
 		m_upnp = new upnp(m_io_service, m_half_open
 			, m_listen_interface.address()
@@ -2140,7 +2142,7 @@ namespace aux {
 				, m_dht_settings.service_port 
 				, m_dht_settings.service_port);
 #endif
-		return m_upnp;
+		return m_upnp.get();
 	}
 
 	void session_impl::stop_lsd()