<div class="content" name="WitnessrRegister" uuid="90803d2e-948f-42ce-a0c8-a4a963935d22"><p>The WitnessrRegister method allows the witness client to
register for resource state change notifications of a NetName and IPAddress.
The client can subsequently call the WitnessrAsyncNotify method to receive
notifications when there is a state change on any of these resources.</p><dl>
<dd>
<div><pre> DWORD WitnessrRegister(
         [in] handle_t Handle,
         [out] PPCONTEXT_HANDLE ppContext,
         [in] ULONG Version,
         [in] [string] [unique] LPWSTR NetName,
         [in] [string] [unique] LPWSTR IpAddress,
         [in] [string] [unique] LPWSTR ClientComputerName);
            
</pre></div>
</dd></dl><p><b>Handle:</b> An RPC binding handle <a href="https://go.microsoft.com/fwlink/?LinkId=89824" data-linktype="external">[C706]</a>.</p><p><b>ppContext:</b> A context handle of type
PPCONTEXT_HANDLE, as specified in section <a href="de9b6be4-c32d-4187-87b3-5de2a8f48f67" data-linktype="relative-path">2.2.1.2</a>, that identifies
the client on the server.</p><p><b>Version:</b>  The version of the Witness protocol
currently in use by the client.</p><p><b>NetName:</b>  A pointer to a null-terminated
string that specifies the name of the resource for which the client requires
notifications.</p><p><b>IpAddress:</b>  A pointer to a null-terminated
string that specifies the IP address to which the client application connection
is established.</p><p><b>ClientComputerName:</b>  A pointer to a
null-terminated string that is used to identify the Witness client.</p><p><b>Return Values:</b> Returns 0x00000000
(ERROR_SUCCESS) on success or a nonzero error code, as specified in <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>
section <a href="../ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d" data-linktype="relative-path">2.2</a>.
The most common error codes are listed in the following table.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 ERROR_SUCCESS</td>
  <td>The operation completed successfully.</td>
 </tr><tr>
  <td>0x00000005 ERROR_ACCESS_DENIED</td>
  <td>Access is denied.</td>
 </tr><tr>
  <td>0x000005AA ERROR_NO_SYSTEM_RESOURCES</td>
  <td>Insufficient system resources exist to complete the requested service.</td>
 </tr><tr>
  <td>0x00000057 ERROR_INVALID_PARAMETER</td>
  <td>The parameter is incorrect.</td>
 </tr><tr>
  <td>0x0000139F ERROR_INVALID_STATE</td>
  <td>The specified resource state is invalid.</td>
 </tr><tr>
  <td>0x0000051A ERROR_REVISION_MISMATCH</td>
  <td>The client request contains an invalid Witness protocol version.</td>
 </tr></tbody></table>
</dd></dl><p>If the <b>Version</b> field of the request is not
0x00010001, the server MUST stop processing the request and return the error
code ERROR_REVISION_MISMATCH.</p><p>If <i>NetName</i>, <i>IpAddress</i> or <i>ClientComputerName</i>
is NULL, the server MUST fail the request and return the error code
ERROR_INVALID_PARAMETER.</p><p>If the <i>NetName</i> parameter is not equal to <b>ServerGlobalName</b>,
the server MUST fail the request and return the error code
ERROR_INVALID_PARAMETER. </p><p>The server MUST enumerate the shares by calling <b>NetrShareEnum</b>
as specified in <a href="../ms-srvs/accf23b0-0f57-441c-9185-43041f1b0ee9" data-linktype="relative-path">[MS-SRVS]</a>
section <a href="../ms-srvs/c4a98e7b-d416-439c-97bd-4d9f52f8ba52" data-linktype="relative-path">3.1.4.8</a>.
In the enumerated list, if any of the shares has shi*_type set to
STYPE_CLUSTER_SOFS, as specified in [MS-SRVS] section <a href="../ms-srvs/6069f8c0-c93f-43a0-a5b4-7ed447eb4b84" data-linktype="relative-path">2.2.2.4</a>,
the server MUST search for an <b>Interface</b> in <b>InterfaceList</b>, where <b>Interface.IPv4Address</b>
or <b>Interface.IPv6Address</b> matches the <i>IpAddress</i> parameter based on
its format. If no matching entry is found, the server MUST fail the request and
return the error code ERROR_INVALID_STATE.</p><p>The server MUST create a <b>WitnessRegistration</b> entry as
follows and insert it into the <b>WitnessRegistrationList</b>. </p><ul><li><p><span><span> 
</span></span><b>WitnessRegistration.WitnessClientName</b> MUST be set to the <i>ClientComputerName</i>
parameter.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.NetworkName</b> MUST be set to the <i>NetName</i>
parameter.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.IPAddress</b> MUST be set to the <i>IPAddress</i>
parameter.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.RegistrationKey</b> MUST be set to a <a href="bdf33531-fabc-46df-8252-1100c9c0da85#gt_c4813fc3-b2e5-4aa3-bde7-421d950d68d3" data-linktype="relative-path">UUID</a> generated by the
server.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.PendingChangeNotifications</b> and <b>WitnessRegistration.PendingMoveNotification</b>
MUST be set to empty.</p>
</li></ul><p>If <b>WitnessServiceVersion</b> is 0x00020000, the server
MUST set the following values in <b>WitnessRegistration</b> entry:</p><ul><li><p><span><span> 
</span></span><b>WitnessRegistration.WitnessClientVersion</b> MUST be set to
the value of the <i>Version</i> parameter value in the request.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.ShareName</b> MUST be set to empty.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.ShareNameNotificationRequired</b> MUST be
set to FALSE.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.IPNotificationRequired</b> MUST be set to
FALSE.</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.PendingShareMoveNotification</b> MUST be
set to empty</p>
</li><li><p><span><span> 
</span></span><b>WitnessRegistration.PendingIPNotification</b> MUST be set to
empty.</p>
</li></ul><p>The server MUST copy the <b>WitnessRegistration.RegistrationKey</b>
into the <i>ppContext</i> parameter.</p><p>The server MUST return ERROR_SUCCESS and the <i>ppContext</i>
parameter to the caller.</p></div>