README

从 JulioECastro/Skype-for-Business-UCWA-PHP 分支而来

索引

1. 关于
   1.1 什么是Skype for Business？
   1.2 什么是(Skype for Business) UCWA？
   1.3 为什么我需要这个类？
   
2. 如何以及为什么
   2.1 第一步
   2.2 初始化 UCWA_init
   2.3 获取访问令牌
   2.4 初始化 UCWA_use
   2.5 注册应用程序
   2.6 创建对话
   2.7 等待接受
   2.8 发送消息
   2.9 终止对话
   2.10 删除应用程序
   2.11 请求工作流
   

这就是为什么您需要这个类的原因。它允许您同时向多个接收者发送即时消息。并且它使用Skype UCWA所需的所有标准。

官方UCWA网站

2 如何以及为什么

2.1 第一步

首先，您必须为您的环境设置Autodiscover-URL。Autodiscover-URL通常如下所示：https://lyncdiscover.yourdomain.com。通过编辑本地副本的base.ucwa.class.php来更改该URL。存储此URL的变量位于文件的上部区域。

复制lib/目录，并将base.ucwa.class.php文件包含在任何您想使用类的位置。

<?php
  require( "lib/base.ucwa.class.php" );
?>

这将加载两个类，您将能够使用它们。一方面是UCWA_init，另一方面是UCWA_use。

2.2 初始化 UCWA_init

UCWA_init用于进行基本操作，如自动发现和身份验证（更多信息）。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
?>

UCWA_init 构造函数需要您的应用的 FQDN（完全合格域名） 作为第一个和最后一个参数。您的 FQDN 必须允许在 Skype for Business 或 Lync 服务器上使用。 请注意，带有 http:// 的域名与带有 https:// 的域名不同。

得益于构造函数，UCWA_init 类将自动发现用户、应用和 XFrame 源所需的 URL。

2.3 获取访问令牌

一旦完成 Autodiscover 配置，您必须请求一个访问令牌以供进一步使用。使用方法 getAccessToken( $username, $password ) 来执行必要的请求。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
?>

您的用户名取决于服务器配置。通常，您可以使用您的 SIP 地址或内部域名后跟您的 NT 账户 (domain\user)。您用于身份验证的用户将作为您的 IM 接收者的可见发送者。

2.4 初始化 UCWA_use

完成了 Autodiscover 和身份验证等基本操作后，我们将使用高级功能。但首先，我们需要初始化这些高级功能。为此，我们使用 UCWA_use。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
?>

在这个简短的示例中，UCWA_use 的构造函数不需要任何参数。但如果您想使用多文件解决方案，您必须通过使用 UCWA_init 方法 getUCWAData() 导出 Autodiscover 和身份验证数据，该方法将返回一个数组。然后您必须将数组值传递给 UCWA_use 的构造函数。有关更多信息，请参阅高级示例。

2.5 注册应用

在构造函数之外，使用 UCWA_use 的第一个实际步骤是注册您的应用。如果您想同时发送多条消息，您应该为每次对话注册您的应用。这将生成一个唯一的 ID，允许您跟踪对话和消息的状态。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
?>

您可以将任何您想要的名称指定为应用名称（registerApplication() 的第一个参数）。它不会在对话或其他地方显示，除了服务器日志。

2.6 创建对话

完成您的应用的注册后，您就可以开始对话了。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
  $im->createConversation( "sip:another.one@yourdomain.com", "Subject" );
?>

只需将接收者作为第一个参数传递，将对话的主题作为第二个参数。

2.7 等待接受

UCWA_use 中的 createConversation 方法将生成一个对话邀请，接收者必须接受。如果用户忽略邀请或离线，则以下方法 waitForAccept 将返回 false。如果接收者可用且在 30 秒内没有点击 "忽略"（取决于配置），对话将自动接受。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
  $im->createConversation( "sip:another.one@yourdomain.com", "Subject" );
  
  if ( $im->waitForAccept() ) {
    // ...
  }
?>

2.8 发送消息

一旦对话被接受，我们最终可以发送消息了。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
  $im->createConversation( "sip:another.one@yourdomain.com", "Subject" );
  
  if ( $im->waitForAccept() ) {
    $im->sendMessage( "First message!" );
  }
?>

只需将您的消息作为参数传递给 UCWA_use 中的 sendMessage。当然，您可以通过重复使用 sendMessage 方法发送多条消息。

2.9 终止对话

还有什么要说的吗？一旦您发送了所有消息，就应该结束对话。但在您能够发送结束命令之前，您首先需要检查事件通道。我们使用已经熟悉的 waitForAccept 方法来做这件事。但这次，我们用参数 false 来调用这个方法。这确保了该方法不会等待任何事情。相反，它只会检查对话是否由于连接问题或用户交互而失去了连接。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
  $im->createConversation( "sip:another.one@yourdomain.com", "Subject" );
  
  if ( $im->waitForAccept() ) {
    $im->sendMessage( "First message!" );
    // Send more messages
    
    $im->waitForAccept( false );
  }
?>

只有在那时，您才能使用 terminateConversation 方法。它将优雅地关闭连接，Skype for Business 或 Lync 客户端可能会告诉接收者对话已经结束。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
  $im->createConversation( "sip:another.one@yourdomain.com", "Subject" );
  
  if ( $im->waitForAccept() ) {
    $im->sendMessage( "First message!" );
    // Send more messages
    
    $im->waitForAccept( false );
    $im->terminateConversation();
  }
?>

2.10 删除应用程序

为了避免 HTTP/1.1 410 Gone，您应该始终在最后删除您的应用程序。通过使用 deleteApplication 来实现。

<?php
  require( "lib/base.ucwa.class.php" );
  $ucwa = new UCWA_init( "http://myapp.example.com" );
  $ucwa->getAccessToken( "some.user@yourdomain.com", "P@ssw0rd!" );
  
  $im = new UCWA_use();
  $im->registerApplication( "My Application" );
  $im->createConversation( "sip:another.one@yourdomain.com", "Subject" );
  
  if ( $im->waitForAccept() ) {
    $im->sendMessage( "First message!" );
    // Send more messages
    
    $im->waitForAccept( false );
    $im->terminateConversation();
	$im->deleteApplication();
  }
?>

2.11 请求工作流程

3 更新日志

0.1.0

• 从 JulioECastro/Skype-for-Business-UCWA-PHP 初始分支
• 将文件组织成 Composer 包

0.1.1

• 通过初始化数组添加到配置中，例如。

    $skype_config = [
        'ucwa_autodiscover' => 'https://webdir.online.lync.com/autodiscover/autodiscoverservice.svc/root',
        'ucwa_user' => 'beavis',
        'ucwa_password' => 'firekicksass'
    ];

    $init = new InitConnection('http://local.services.myproject.com:8001', $skype_config);