NWSMTSConnectToTargetServiceEx

Connects an engine to a specified Target Service and also supports passwords with international and extended characters.

Syntax

  #include <smsutapi.h> 
  #include <smstsapi.h> 
   
  CCODE NWSMTSConnectToTargetServiceEx (
     UINT32  *connection, 
     STRING   targetServiceName, 
     STRING   targetUserName, 
     void    *authentication
     UINT32   optionFlag
     );

Parameters

connection

(IN/OUT) Specifies a pointer to the connection information from NWSMConnectToTSA. Outputs a pointer to the connection to the Target Service in addition to the input information.

targetServiceName

(IN) Specifies the Target Service name returned by NWSMTSScanTargetServiceName or NWSMTSListTargetServices.

targetUserName

(IN) Specifies the user name on a file server (maximum size is NWSM_MAX_TARGET_USER_NAME_LEN).

authentication

(IN) Points to the authentication data necessary to establish a connection with the Target Service (for example, a user password).

optionflag

(IN) Specifies the type of the authentication data.

Return Values

See Section 9.3, Target Service Return Values for more information.

The following table lists the return values associated with the functi on.

0x00000000

Successful

0xFFFDFFD7

NWSMTS_LOGIN_DENIED

0xFFFDFFE7

NWSMTS_INVALID_CONNECTION_HANDL

0xFFFDFFC8

NWSMTS_OVERFLOW

0xFFFEFFF2

NWSMDR_INVALID_PROTOCOL

0xFFFEFFE0

NWSMDR_CORRUPTED_STATE

0xFFFEFFE9

NWSMDR_INVALID_CONTEXT

0xFFFEFFFF

NWSMDR_INVALID_CONNECTION

0xFFFDFFAD

NWSMTS_UNSUPPORTED_OPTION

Remarks

Before NWSMTSConnectToTargetService is called, the engine must be connected to a TSA that has access to the desired target.

targetServiceName should contain a Target Service name from the name list returned by NWSMTSListTargetServices.

NWSMTSConnectToTargetService connects an engine to the specified Target Service and establishes the user's rights on the Target Service. After successfully connecting, the engine can access the Target Service’s data.

An engine can connect to only one Target Service per TSA connection. This means that a Target Service can have multiple connections, but each connection must be referenced by a different TSA connection.

targetUserName contains the user name that allows proper access to the Target Service’s data.

authentication is defined using the optionflag parameter. However, the SMDR encrypt/decrypts it if it is passed between SMDRs. If no authentication is passed, set the length to zero. Do not pass a NULL pointer.

The following option flags are supported.

Option Flags

Description

NWSM_AUTH_UTF8_DATA

The authentication data is a length preceded (UINT16) UTF-8 string

NWSM_AUTH_UNICODE_DATA

The authentication data is a length preceded (UINT16) Unicode string.

NWSM_AUTH_RAW_DATA

The authentication data is a length preceded (UINT16) string.

NOTE:This flag provides the same functionality as NWSM_AUTH_LOCAL_DATA and has been renamed to accurately reflect the data type. Any existing usage of NWSM_AUTH_LOCAL_DATA will continue to be supported.

NWSM_AUTH_CASA_TOKEN

The authentication data is a length preceded (UINT 16) CASA token and targetUserName should be set to “CasaPrincipal”.

NOTE:This symbol is not present in the SMS import file, as all versions of SMS do not export this symbol. To use this function, programmatically import the symbol and invoke it.

See Also

NWSMConnectToTSA, NWSMTSScanTargetServiceName, NWSMTSListTargetServices