内容

名称

Net::NNTP - NNTP 客户端类

概要

use Net::NNTP;

$nntp = Net::NNTP->new("some.host.name");
$nntp->quit;

# start with SSL, e.g. nntps
$nntp = Net::NNTP->new("some.host.name", SSL => 1);

# start with plain and upgrade to SSL
$nntp = Net::NNTP->new("some.host.name");
$nntp->starttls;

描述

Net::NNTP 是一个用 Perl 实现的简单 NNTP 客户端类，如 RFC977 和 RFC4642 中所述。如果安装了 IO::Socket::SSL，它还支持隐式和显式 TLS 加密，即 NNTPS 或 NNTP+STARTTLS。

Net::NNTP 类是 Net::Cmd 的子类，并且（取决于可用性）是 IO::Socket::IP、IO::Socket::INET6 或 IO::Socket::INET 的子类。

类方法

new([$host][, %options])

这是用于创建新的 Net::NNTP 对象的构造函数。$host 是需要建立 NNTP 连接的远程主机的名称。如果未提供，则可以作为下面描述的 Host 选项传递。如果未传递主机，则会检查两个环境变量，首先是 NNTPSERVER，然后是 NEWSHOST，然后是 Net::Config，如果未找到主机，则使用 news。

%options 以哈希方式传递，使用键值对。可能的选项包括

主机 - 要连接的 NNTP 主机。它可以是单个标量，如 IO::Socket::INET 中定义的 PeerAddr 选项，也可以是包含要依次尝试的主机的数组的引用。 "host" 方法将返回用于连接到主机的值。

端口 - 要连接的端口。默认 - 119 用于普通 NNTP，563 用于立即 SSL (nntps)。

SSL - 如果连接应该从一开始就使用 SSL，而不是稍后使用 starttls 升级。您可以使用 IO::Socket::SSL 中记录的 SSL 参数，但它通常会使用正确的参数。

超时 - 从 NNTP 服务器等待响应的最大时间（以秒为单位），值为零将导致所有 IO 操作阻塞。（默认值：120）

调试 - 启用将调试信息打印到 STDERR

阅读器 - 如果远程服务器是 INN，那么最初连接将是到 innd，默认情况下 Net::NNTP 将发出 MODE READER 命令，以便远程服务器变为 nnrpd。如果 Reader 选项的值为零，则不会发送此命令，连接将保持与 innd 的通信状态。

LocalAddr 和 LocalPort - 这些参数直接传递给 IO::Socket，以允许将套接字绑定到特定的本地地址和端口。

域 - 此参数直接传递给 IO::Socket，并使其能够即使使用 IO::Socket::IP 作为超类，也能强制执行 IPv4 连接。或者，可以使用 Family。

对象方法

除非另有说明，否则所有方法都返回 true 或 false 值，其中 true 表示操作成功。当方法声明它返回一个值时，失败将返回为 undef 或空列表。

Net::NNTP 继承自 Net::Cmd，因此除了此处记录的方法外，还可以使用 Net::Cmd 中定义的方法向远程 NNTP 服务器发送命令。

host()

返回构造函数使用的值，并传递给 IO::Socket::INET，以连接到主机。

starttls()

将现有的纯连接升级到 SSL。SSL 所需的任何参数都必须在 new 中给出。

article([{$msgid|$msgnum}[, $fh]])

检索指定文章的标题、空行和正文（文本）。

如果指定了$fh，则它应该是一个有效的文件句柄，结果将被打印到该句柄。成功时将返回一个真值。如果未指定$fh，则成功时的返回值将是对包含请求文章的数组的引用，数组中的每个条目都包含文章的一行。

如果没有传递参数，则将获取当前选择新闻组中的当前文章。

$msgnum是当前新闻组中文章的数字 ID，它将改变当前文章指针。$msgid是文章的邮件 ID，如该文章标题中所示。预计客户端将从newnews命令提供的列表中获取$msgid，从其他文章中包含的引用中获取，或从对其他命令的响应中提供的邮件 ID 中获取。

如果出现错误，将返回undef。

body([{$msgid|$msgnum}[, [$fh]])

与article类似，但只获取文章的正文。

head([{$msgid|$msgnum}[, [$fh]])

与article类似，但只获取文章的标题。

articlefh([{$msgid|$msgnum}])
bodyfh([{$msgid|$msgnum}])
headfh([{$msgid|$msgnum}])

这些与article()、body() 和 head() 类似，但它们不直接返回请求的数据，而是返回一个绑定文件句柄，从中可以读取文章。

nntpstat([{$msgid|$msgnum}])

nntpstat命令类似于article命令，但不会返回任何文本。在组内按消息编号选择时，nntpstat命令用于设置“当前文章指针”，而不会发送文本。

使用nntpstat命令按邮件 ID 选择是有效的，但价值可疑，因为按邮件 ID 选择不会改变“当前文章指针”。

返回“当前文章”的邮件 ID。

group([$group])

设置和/或获取当前组。如果未提供$group，则返回有关当前组的信息。

在标量上下文中，它返回组名。

在数组上下文中，返回值是一个列表，包含组中的文章数量、第一篇文章的编号、最后一篇文章的编号以及组名。

help()

从服务器请求帮助文本（对该实现理解的命令的简短摘要）。返回文本或在失败时返回 undef。

ihave($msgid[, $message])

ihave 命令通知服务器客户端拥有 ID 为 $msgid 的文章。如果服务器需要该文章的副本并且已提供 $message，则会发送该副本。

如果服务器需要该文章并且成功发送了 $message（如果指定），则返回 true。

如果未指定 $message，则必须使用 Net::Cmd 中的 datasend 和 dataend 方法发送消息。

$message 可以是行数组或对数组的引用，并且必须由调用者编码为所需编码的八位字节，例如，使用 Encode 模块的 encode() 函数。

last()

将“当前文章指针”设置为当前新闻组中的上一篇文章。

返回文章的 message-id。

date()

返回远程服务器上的日期。此日期将采用 UNIX 时间格式（自 1970 年以来的秒数）。

postok()

如果服务器的初始响应表明它允许发布，则 postok 将返回 true。

authinfo($user, $pass)

使用提供的用户名和密码对服务器进行身份验证（使用 RFC2980 中定义的原始 AUTHINFO USER / AUTHINFO PASS 形式）。请注意，密码将以明文形式发送到服务器。除非与服务器的连接以某种方式受到保护，否则不应将此命令与有价值的密码一起使用。

authinfo_simple($user, $pass)

使用提供的用户名和密码验证到服务器（使用 RFC2980 中定义和弃用的建议 NNTP V2 AUTHINFO SIMPLE 形式）。与 "authinfo" 一样，密码以明文形式发送。

list()

获取有关所有活动新闻组的信息。结果是对一个哈希的引用，其中键是组名，每个值是对一个数组的引用。此数组中的元素是：- 组中的最后一条文章编号、组中的第一条文章编号以及有关组的任何信息标志。

newgroups($since[, $distributions])

$since 是一个时间值，$distributions 是一个分发模式或对分发模式列表的引用。结果与 list 相同，但返回的组将限于在 $since 之后创建的组，如果指定，则位于 $distributions 中的某个分发区域。

newnews($since[, $groups[, $distributions]])

$since 是一个时间值。$groups 是一个组模式或对组模式列表的引用。$distributions 是一个分发模式或对分发模式列表的引用。

返回对一个列表的引用，该列表包含在 $since 之后发布的所有新闻的 message-id，这些新闻位于与 $groups 匹配的组中，并且分发与 $distributions 匹配。

next()

将“当前文章指针”设置为当前新闻组中的下一篇文章。

返回文章的 message-id。

post([$message])

向新闻服务器发布新文章。如果指定了 $message 并且允许发布，则将发送该消息。

如果未指定 $message，则必须使用 Net::Cmd 中的 datasend 和 dataend 方法发送消息。

$message 可以是行数组或对数组的引用，并且必须由调用者编码为所需编码的八位字节，例如，使用 Encode 模块的 encode() 函数。

通过 datasend 发送的消息或作为 $message 参数发送的消息必须采用 RFC822 中描述的格式，并且必须包含 From:、Newsgroups: 和 Subject: 标头。

postfh()

使用绑定的文件句柄将新文章发布到新闻服务器。如果允许发布，此方法将返回一个绑定的文件句柄，您可以将文章内容打印到该句柄以进行发布。您必须在完成发布文章后显式关闭()文件句柄，close()调用的返回值将指示消息是否成功发布。

slave()

告诉远程服务器我不是用户客户端，而是可能是另一个新闻服务器。

quit()

退出远程服务器并关闭套接字连接。

can_inet6()

返回我们是否可以使用 IPv6。

can_ssl()

返回我们是否可以使用 SSL。

扩展方法

这些方法使用 RFC977 文档中未包含的命令。一些服务器可能不支持所有这些命令。

newsgroups([$pattern])

返回对哈希的引用，其中键是与$pattern匹配的所有组名，或者如果没有指定模式，则为所有组，每个值包含该组的描述文本。

distributions()

返回对哈希的引用，其中键是所有可能的分布名称，值是分布描述。

distribution_patterns()

返回对数组的引用，其中每个元素（本身也是数组引用）包含 distrib.pats 列表中的一行，该列表由一些 NNTP 服务器维护，即：权重、通配符和客户端可以使用该值来构建 Distribution 标头的值。

subscriptions()

返回对列表的引用，该列表包含建议新用户订阅的组列表。

overview_fmt()

返回对数组的引用，该数组包含xover返回的字段名称。

active_times()

返回对哈希的引用，其中键是组名，每个值是对数组的引用，该数组包含组创建的时间和创建者的标识符（可能是电子邮件地址）。

active([$pattern])

类似于 list，但只返回与模式匹配的活动组。$pattern 可以是组模式。

xgtitle($pattern)

返回一个哈希的引用，其中键是所有与 $pattern 匹配的组名，每个值是该组的描述文本。

xhdr($header, $message_spec)

获取所有指定消息的 $header 标头字段。

返回值将是一个哈希的引用，其中键是消息编号，每个值包含该消息的请求标头的文本。

xover($message_spec)

返回值将是一个哈希的引用，其中键是消息编号，每个值包含一个数组的引用，该数组包含该消息的概述字段。

可以通过调用 overview_fmt 获取字段名称。

xpath($message_id)

返回包含指定消息的服务器上文件的路径名。

xpat($header, $pattern, $message_spec)

结果与 xhdr 相同，只是结果将被限制在标头文本与 $pattern 匹配的标头上。

xrover($message_spec)

XROVER 命令返回指定文章的引用信息。

返回一个 HASH 的引用，其中键是消息编号，值是文章中的 References: 行。

listgroup([$group])

返回一个包含 $group 中所有活动消息的列表的引用，如果未指定 $group，则返回当前组。

reader()

告诉服务器你是读者，而不是另一个服务器。

某些服务器需要此命令。例如，如果您连接到 INN 服务器并且您具有传输权限，您的连接将连接到传输守护程序，而不是 NNTP 守护程序。发出此命令将导致传输守护程序将控制权移交给 NNTP 守护程序。

某些服务器不理解此命令，但发出它并忽略响应是无害的。

不支持

以下 NNTP 命令不受此软件包支持，并且没有计划这样做。

AUTHINFO GENERIC
XTHREAD
XSEARCH
XINDEX

定义

$message_spec

$message_spec 可以是单个消息 ID、单个消息编号，或对两个消息编号列表的引用。

如果 $message_spec 是对两个消息编号列表的引用，并且范围内的第二个编号小于或等于第一个编号，则该范围表示第一个消息编号之后组中的所有消息。

注意 出于与早期版本的 Net::NNTP 的兼容性原因，消息规范可以作为两个数字的列表传递，这已过时，现在应该传递对该列表的引用。

$pattern

NNTP 协议使用 WILDMAT 格式进行模式匹配。WILDMAT 格式最初由 Rich Salz 开发，其基于 UNIX "find" 命令中用于描述文件名的格式。它的开发是为了提供一种统一的机制，以与 UNIX shell 匹配文件名的相同方式匹配模式。

在测试匹配时，模式在每个字符串的开头和结尾隐式地锚定。

除了模式和要检查匹配的源之间严格的一对一匹配之外，还有五种模式匹配操作。

第一个是星号 *，用于匹配任何零个或多个字符的序列。

第二个是问号 ?，用于匹配任何单个字符。第三个指定一组特定的字符。

该集合被指定为字符列表，或作为字符范围，其中范围的开头和结尾由减号（或破折号）字符分隔，或作为列表和范围的任何组合。如果破折号是集合的开头或结尾，则破折号也可以包含在集合中。此集合用方括号括起来。如果右方括号 ] 是集合中的第一个字符，则可以使用它。

第四个操作与第三个操作的逻辑非相同，并且以与第三个相同的方式指定，只是在测试字符串的开头添加了一个插入符号 ^，位于打开的方括号内。

最后一个操作使用反斜杠字符来使打开的方括号 [、星号、反斜杠或问号的特殊含义无效。两个连续的反斜杠将导致反斜杠作为没有特殊含义的字符进行评估。

示例
[^]-]

匹配除右方括号或减号/连字符以外的任何单个字符。

*bdc

匹配任何以字符串“bdc”结尾的字符串，包括字符串“bdc”（不带引号）。

[0-9a-zA-Z]

匹配任何单个可打印的字母数字 ASCII 字符。

a??d

匹配任何以 a 开头、以 d 结尾的四个字符字符串。

导出

无.

已知错误

请参阅 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet。

另请参阅

Net::Cmd，IO::Socket::SSL。

作者

Graham Barr <[email protected]>。

Steve Hay <[email protected]> 从 1.22_02 版本开始维护 libnet。

版权

版权所有 (C) 1995-1997 Graham Barr。保留所有权利。

版权所有 (C) 2013-2016, 2020 Steve Hay。保留所有权利。

许可证

本模块是自由软件；您可以根据与 Perl 本身相同的条款重新发布和/或修改它，即根据 GNU 通用公共许可证或 Artistic 许可证的条款，如 LICENCE 文件中所述。

版本

版本 3.15

日期

2023 年 3 月 20 日

历史

请参阅 Changes 文件。