create_identity

Logs a user in to an eDirectory tree and returns an identity token.

Library:LibC
Classification:Novell
Service:NCP Client

Syntax

  #include <client.h>
   
  int create_identity (
     const char      *treename,
     const void      *username,
     const char      *password,
     const void      *nmas_sequence,
     unsigned long    flags,
     int             *identity);

Parameters

treename

(IN) Points to string containing the name of the tree. If NULL or an empty string, the current tree is used.

To use a tree name, you must have set up address resolution to resolve a tree name into a physical address. If you haven't set up address resolution to do this or if you prefer to use a server name, you can use a server name in this parameter. However, address resolution must be set up to resolve server names into physical addresses (which is the defined behavior on most networks).

username

(IN) Points to a string containing the fully distinguished name of the user. It can be of type ASCII, UTF-8, or Unicode, as specified by the flags parameter. It can be expressed in any of the following formats:

  • jdoe.sales.acme
  • .jdoe.sales.acme
  • cn=jdoe.ou=sales.o=acme
  • .cn=jdoe.ou=sales.o-acme
password

(IN) Points to a string containing the user's password. The password must be ASCII text in the local code page.

nmas_sequence

(IN) Pass in NULL. Not currently used.

flags

(IN) Specifies the transport type and the username string type. Select a flag for each:

Flag

Value

Description

XPORT_WILD

0x0000

Indicates no preference and to use whatever transport is available.

XPORT_IPX

0x0001

Indicates a preference for Novell IPX.

XPORT_TCP

0x0002

Indicates a preference for TCP.

USERNAME_ASCII

0x00000

Indicates that the username is an ASCIIZ string. This is the default.

USERNAME_UTF8

0x10000

Indicates that the username is a UTF-8 string.

USERNAME_UNICODE

0x20000

Indicates that the username is a Unicode string.
identity

(OUT) Points to the returned identity token.

Return Values

If successful, returns 0; otherwise returns a nonzero error.

Decimal

Constant

Description

5

ENOMEM

Unable to allocate memory for the identity.

21

ERESOURCE

The NICI infrastructure is missing.

65

ENAMETOOLONG

The tree name element is too long.

83

EHOSTUNREACH

Either the server cannot be found or a server with the specified user cannot be found.

105

ENOCONTEXT

The calling thread has no context.

108

ENAMEINVAL

The username parameter is missing.

Remarks

You can use the identity token to accomplish the following tasks:

  • To create a path context. See NXCreatePathContext in Volume 1.

  • To establish an NCP session with a NetWare server, which then allows you to access its services remotely.

If you pass in the same credentials to create a second identity token for the user, you receive back the same token, but its use count is incremented for each requested token.

See Also