Share via

3.1.4.1 ClientAttach (Opnum 0)

  • Article

The ClientAttach method is called by the client to establish a binding instance with the server.

 long ClientAttach(
   [out] PCONTEXT_HANDLE_TYPE* pphContext,
   [in] long lProcessID,
   [out] long* phAsyncEventsEvent,
   [in, string] wchar_t* pszDomainUser,
   [in, string] wchar_t* pszMachine
 );

pphContext: Pointer to a PCONTEXT_HANDLE_TYPE context handle.

lProcessID: Identifier of the process on the client that generated the attach request.

Value

Meaning

0xFFFFFFFF

Client is a remote instance that wants to control the telephony devices on this server.

0xFFFFFFFD

Client is a remote instance that wants to manage and administer the telephony server.

phAsyncEventsEvent: If applicable, a pointer to a packet containing any asynchronous event that was triggered by the client attaching to the server.

If lProcessId equals 0xFFFFFFFF (-1) and the server supports the NegotiateAPIVersionForAllDevices request, the server MUST set the value of phAsyncEventsEvent to 0xa5c369a5.

If lProcessId equals 0xFFFFFFFD (-3), the server MUST set the value of phAsyncEventsEvent to 0x32323232 for a 32-bit platform or to 0x64646464 for a 64-bit platform.

pszDomainUser: Pointer to a null-terminated string indicating the user's domain account name. The string is passed on the wire.

If lProcessId equals 0xFFFFFFFF (-1), pszDomainUser MUST contain either an empty string ("") or the name of a client mailslot. If a mailslot name is specified and the server is able to successfully open the mailslot, then the client and the server MUST use the "pull" model event scheme. The server MUST inform the client that events are available for retrieval by writing a DWORD value to the client's mailslot, and the client retrieves events via the ClientRequest method. If an empty string is specified or the server is unable to open the client's mailslot, then the "push" model event scheme MUST be used in which the server calls the client's RemoteSPEventProc method.

If lProcessId equals 0xFFFFFFFD (-3), pszDomainUser MUST contain the user name. The client in this case is an MMC client that is not interested in events occurring on the telephony devices.

pszMachine: Pointer to a null-terminated string indicating the client's machine name. The string MUST be passed on the wire.

If lProcessId equals 0xFFFFFFFF (-1), the pszMachine string takes the following format: <clientComputerName>"<protocolSequence1>"<endpoint1>"<protSeqN>"<epN>"\0. This allows the client to inform the server of its machine name and what protocols and endpoints are supported by the client on its remotesp interface. Quotation marks MUST be used as delimiting tokens. For instance, CLIENT-PC-NAME"ncacn_ip_tcp"251"ncacn_nb_nb"251"\0.

If lProcessId equals 0xFFFFFFFD (-3), pszMachine MUST contain the computer name.

Return Values: The method returns 0 on success; otherwise, it returns a nonzero error code, as specified in [MS-ERREF]. The following table includes a common error code.

Return value/code

Description

0x80000048

LINEERR_OPERATIONFAILED

Generic error on the server.

-19

Requesting administrator access via lProcessId equals 0xFFFFFFFD (-3), but the user credentials of the client do not have administrator access on the server.

On success, the server adds the client to the client list and updates the client's machine name and the user's domain account name.

Exceptions Thrown:

No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

The opnum field value for this method is 0.

Either the client or the server can reject unencrypted packets based on the configuration.<6>