Back to index

lightning-sunbird  0.9+nobinonly
nsspki1.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef NSSPKI1_H
00038 #define NSSPKI1_H
00039 
00040 #ifdef DEBUG
00041 static const char NSSPKI1_CVS_ID[] = "@(#) $RCSfile: nsspki1.h,v $ $Revision: 1.3 $ $Date: 2005/01/20 02:25:49 $";
00042 #endif /* DEBUG */
00043 
00044 /*
00045  * nsspki1.h
00046  *
00047  * This file contains the prototypes of the public NSS routines 
00048  * dealing with the PKIX part-1 definitions.
00049  */
00050 
00051 #ifndef NSSBASET_H
00052 #include "nssbaset.h"
00053 #endif /* NSSBASET_H */
00054 
00055 #ifndef NSSPKI1T_H
00056 #include "nsspki1t.h"
00057 #endif /* NSSPKI1T_H */
00058 
00059 #ifndef OIDDATA_H
00060 #include "oiddata.h"
00061 #endif /* OIDDATA_H */
00062 
00063 PR_BEGIN_EXTERN_C
00064 
00065 /*
00066  * NSSOID
00067  *
00068  * The public "methods" regarding this "object" are:
00069  *
00070  *  NSSOID_CreateFromBER   -- constructor
00071  *  NSSOID_CreateFromUTF8  -- constructor
00072  *  (there is no explicit destructor)
00073  * 
00074  *  NSSOID_GetDEREncoding
00075  *  NSSOID_GetUTF8Encoding
00076  */
00077 
00078 extern const NSSOID *NSS_OID_UNKNOWN;
00079 
00080 /*
00081  * NSSOID_CreateFromBER
00082  *
00083  * This routine creates an NSSOID by decoding a BER- or DER-encoded
00084  * OID.  It may return NSS_OID_UNKNOWN upon error, in which case it 
00085  * will have created an error stack.
00086  *
00087  * The error may be one of the following values:
00088  *  NSS_ERROR_INVALID_BER
00089  *  NSS_ERROR_NO_MEMORY
00090  *
00091  * Return value:
00092  *  NSS_OID_UNKNOWN upon error
00093  *  An NSSOID upon success
00094  */
00095 
00096 NSS_EXTERN NSSOID *
00097 NSSOID_CreateFromBER
00098 (
00099   NSSBER *berOid
00100 );
00101 
00102 extern const NSSError NSS_ERROR_INVALID_BER;
00103 extern const NSSError NSS_ERROR_NO_MEMORY;
00104 
00105 /*
00106  * NSSOID_CreateFromUTF8
00107  *
00108  * This routine creates an NSSOID by decoding a UTF8 string 
00109  * representation of an OID in dotted-number format.  The string may 
00110  * optionally begin with an octothorpe.  It may return NSS_OID_UNKNOWN
00111  * upon error, in which case it will have created an error stack.
00112  *
00113  * The error may be one of the following values:
00114  *  NSS_ERROR_INVALID_STRING
00115  *  NSS_ERROR_NO_MEMORY
00116  *
00117  * Return value:
00118  *  NSS_OID_UNKNOWN upon error
00119  *  An NSSOID upon success
00120  */
00121 
00122 NSS_EXTERN NSSOID *
00123 NSSOID_CreateFromUTF8
00124 (
00125   NSSUTF8 *stringOid
00126 );
00127 
00128 extern const NSSError NSS_ERROR_INVALID_STRING;
00129 extern const NSSError NSS_ERROR_NO_MEMORY;
00130 
00131 /*
00132  * NSSOID_GetDEREncoding
00133  *
00134  * This routine returns the DER encoding of the specified NSSOID.
00135  * If the optional arena argument is non-null, the memory used will
00136  * be obtained from that arena; otherwise, the memory will be obtained
00137  * from the heap.  This routine may return return null upon error, in 
00138  * which case it will have created an error stack.
00139  *
00140  * The error may be one of the following values:
00141  *  NSS_ERROR_INVALID_NSSOID
00142  *  NSS_ERROR_NO_MEMORY
00143  *
00144  * Return value:
00145  *  NULL upon error
00146  *  The DER encoding of this NSSOID
00147  */
00148 
00149 NSS_EXTERN NSSDER *
00150 NSSOID_GetDEREncoding
00151 (
00152   const NSSOID *oid,
00153   NSSDER *rvOpt,
00154   NSSArena *arenaOpt
00155 );
00156 
00157 extern const NSSError NSS_ERROR_INVALID_NSSOID;
00158 extern const NSSError NSS_ERROR_NO_MEMORY;
00159 
00160 /*
00161  * NSSOID_GetUTF8Encoding
00162  *
00163  * This routine returns a UTF8 string containing the dotted-number 
00164  * encoding of the specified NSSOID.  If the optional arena argument 
00165  * is non-null, the memory used will be obtained from that arena; 
00166  * otherwise, the memory will be obtained from the heap.  This routine
00167  * may return null upon error, in which case it will have created an
00168  * error stack.
00169  *
00170  * The error may be one of the following values:
00171  *  NSS_ERROR_INVALID_NSSOID
00172  *  NSS_ERROR_NO_MEMORY
00173  *
00174  * Return value:
00175  *  NULL upon error
00176  *  A pointer to a UTF8 string containing the dotted-digit encoding of 
00177  *      this NSSOID
00178  */
00179 
00180 NSS_EXTERN NSSUTF8 *
00181 NSSOID_GetUTF8Encoding
00182 (
00183   const NSSOID *oid,
00184   NSSArena *arenaOpt
00185 );
00186 
00187 extern const NSSError NSS_ERROR_INVALID_NSSOID;
00188 extern const NSSError NSS_ERROR_NO_MEMORY;
00189 
00190 /*
00191  * NSSATAV
00192  *
00193  * The public "methods" regarding this "object" are:
00194  *
00195  *  NSSATAV_CreateFromBER   -- constructor
00196  *  NSSATAV_CreateFromUTF8  -- constructor
00197  *  NSSATAV_Create          -- constructor
00198  *
00199  *  NSSATAV_Destroy
00200  *  NSSATAV_GetDEREncoding
00201  *  NSSATAV_GetUTF8Encoding
00202  *  NSSATAV_GetType
00203  *  NSSATAV_GetValue
00204  *  NSSATAV_Compare
00205  *  NSSATAV_Duplicate
00206  */
00207 
00208 /*
00209  * NSSATAV_CreateFromBER
00210  * 
00211  * This routine creates an NSSATAV by decoding a BER- or DER-encoded
00212  * ATAV.  If the optional arena argument is non-null, the memory used 
00213  * will be obtained from that arena; otherwise, the memory will be 
00214  * obtained from the heap.  This routine may return NULL upon error, 
00215  * in which case it will have created an error stack.
00216  *
00217  * The error may be one of the following values:
00218  *  NSS_ERROR_INVALID_BER
00219  *  NSS_ERROR_NO_MEMORY
00220  *
00221  * Return value:
00222  *  NULL upon error
00223  *  A pointer to an NSSATAV upon success
00224  */
00225 
00226 NSS_EXTERN NSSATAV *
00227 NSSATAV_CreateFromBER
00228 (
00229   NSSArena *arenaOpt,
00230   NSSBER *derATAV
00231 );
00232 
00233 extern const NSSError NSS_ERROR_INVALID_BER;
00234 extern const NSSError NSS_ERROR_NO_MEMORY;
00235 
00236 /*
00237  * NSSATAV_CreateFromUTF8
00238  *
00239  * This routine creates an NSSATAV by decoding a UTF8 string in the
00240  * "equals" format, e.g., "c=US."  If the optional arena argument is 
00241  * non-null, the memory used will be obtained from that arena; 
00242  * otherwise, the memory will be obtained from the heap.  This routine
00243  * may return NULL upon error, in which case it will have created an
00244  * error stack.
00245  *
00246  * The error may be one of the following values:
00247  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
00248  *  NSS_ERROR_INVALID_STRING
00249  *  NSS_ERROR_NO_MEMORY
00250  *
00251  * Return value:
00252  *  NULL upon error
00253  *  A pointer to an NSSATAV upon success
00254  */
00255 
00256 NSS_EXTERN NSSATAV *
00257 NSSATAV_CreateFromUTF8
00258 (
00259   NSSArena *arenaOpt,
00260   NSSUTF8 *stringATAV
00261 );
00262 
00263 extern const NSSError NSS_ERROR_UNKNOWN_ATTRIBUTE;
00264 extern const NSSError NSS_ERROR_INVALID_STRING;
00265 extern const NSSError NSS_ERROR_NO_MEMORY;
00266 
00267 /*
00268  * NSSATAV_Create
00269  *
00270  * This routine creates an NSSATAV from the specified NSSOID and the
00271  * specified data. If the optional arena argument is non-null, the 
00272  * memory used will be obtained from that arena; otherwise, the memory
00273  * will be obtained from the heap.If the specified data length is zero, 
00274  * the data is assumed to be terminated by first zero byte; this allows 
00275  * UTF8 strings to be easily specified.  This routine may return NULL 
00276  * upon error, in which case it will have created an error stack.
00277  *
00278  * The error may be one of the following values:
00279  *  NSS_ERROR_INVALID_ARENA
00280  *  NSS_ERROR_INVALID_NSSOID
00281  *  NSS_ERROR_INVALID_POINTER
00282  *  NSS_ERROR_NO_MEMORY
00283  *
00284  * Return value:
00285  *  NULL upon error
00286  *  A pointer to an NSSATAV upon success
00287  */
00288 
00289 NSS_EXTERN NSSATAV *
00290 NSSATAV_Create
00291 (
00292   NSSArena *arenaOpt,
00293   const NSSOID *oid,
00294   const void *data,
00295   PRUint32 length
00296 );
00297 
00298 extern const NSSError NSS_ERROR_INVALID_ARENA;
00299 extern const NSSError NSS_ERROR_INVALID_NSSOID;
00300 extern const NSSError NSS_ERROR_INVALID_POINTER;
00301 extern const NSSError NSS_ERROR_NO_MEMORY;
00302 
00303 /*
00304  * NSSATAV_Destroy
00305  *
00306  * This routine will destroy an ATAV object.  It should eventually be
00307  * called on all ATAVs created without an arena.  While it is not 
00308  * necessary to call it on ATAVs created within an arena, it is not an
00309  * error to do so.  This routine returns a PRStatus value; if
00310  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
00311  * create an error stack and return PR_FAILURE.
00312  *
00313  * The error may be one of the following values:
00314  *  NSS_ERROR_INVALID_ATAV
00315  *  
00316  * Return value:
00317  *  PR_FAILURE upon error
00318  *  PR_SUCCESS upon success
00319  */
00320 
00321 NSS_EXTERN PRStatus
00322 NSSATAV_Destroy
00323 (
00324   NSSATAV *atav
00325 );
00326 
00327 extern const NSSError NSS_ERROR_INVALID_ATAV;
00328 
00329 /*
00330  * NSSATAV_GetDEREncoding
00331  *
00332  * This routine will DER-encode an ATAV object. If the optional arena
00333  * argument is non-null, the memory used will be obtained from that
00334  * arena; otherwise, the memory will be obtained from the heap.  This
00335  * routine may return null upon error, in which case it will have 
00336  * created an error stack.
00337  *
00338  * The error may be one of the following values:
00339  *  NSS_ERROR_INVALID_ATAV
00340  *  NSS_ERROR_NO_MEMORY
00341  *
00342  * Return value:
00343  *  NULL upon error
00344  *  The DER encoding of this NSSATAV
00345  */
00346 
00347 NSS_EXTERN NSSDER *
00348 NSSATAV_GetDEREncoding
00349 (
00350   NSSATAV *atav,
00351   NSSArena *arenaOpt
00352 );
00353 
00354 extern const NSSError NSS_ERROR_INVALID_ATAV;
00355 extern const NSSError NSS_ERROR_NO_MEMORY;
00356 
00357 /*
00358  * NSSATAV_GetUTF8Encoding
00359  *
00360  * This routine returns a UTF8 string containing a string 
00361  * representation of the ATAV in "equals" notation (e.g., "o=Acme").  
00362  * If the optional arena argument is non-null, the memory used will be
00363  * obtained from that arena; otherwise, the memory will be obtained 
00364  * from the heap.  This routine may return null upon error, in which 
00365  * case it will have created an error stack.
00366  *
00367  * The error may be one of the following values:
00368  *  NSS_ERROR_INVALID_ATAV
00369  *  NSS_ERROR_NO_MEMORY
00370  *
00371  * Return value:
00372  *  NULL upon error
00373  *  A pointer to a UTF8 string containing the "equals" encoding of the 
00374  *      ATAV
00375  */
00376 
00377 NSS_EXTERN NSSUTF8 *
00378 NSSATAV_GetUTF8Encoding
00379 (
00380   NSSATAV *atav,
00381   NSSArena *arenaOpt
00382 );
00383 
00384 extern const NSSError NSS_ERROR_INVALID_ATAV;
00385 extern const NSSError NSS_ERROR_NO_MEMORY;
00386 
00387 /*
00388  * NSSATAV_GetType
00389  *
00390  * This routine returns the NSSOID corresponding to the attribute type
00391  * in the specified ATAV.  This routine may return NSS_OID_UNKNOWN 
00392  * upon error, in which case it will have created an error stack.
00393  *
00394  * The error may be one of the following values:
00395  *  NSS_ERROR_INVALID_ATAV
00396  *
00397  * Return value:
00398  *  NSS_OID_UNKNOWN upon error
00399  *  An element of enum NSSOIDenum upon success
00400  */
00401 
00402 NSS_EXTERN const NSSOID *
00403 NSSATAV_GetType
00404 (
00405   NSSATAV *atav
00406 );
00407 
00408 extern const NSSError NSS_ERROR_INVALID_ATAV;
00409 
00410 /*
00411  * NSSATAV_GetValue
00412  *
00413  * This routine returns an NSSItem containing the attribute value
00414  * in the specified ATAV.  If the optional arena argument is non-null,
00415  * the memory used will be obtained from that arena; otherwise, the
00416  * memory will be obtained from the heap.  This routine may return
00417  * NULL upon error, in which case it will have created an error stack.
00418  *
00419  * The error may be one of the following values:
00420  *  NSS_ERROR_INVALID_ATAV
00421  *  NSS_ERROR_NO_MEMORY
00422  *
00423  * Return value:
00424  *  NULL upon error
00425  *  A pointer to an NSSItem containing the attribute value.
00426  */
00427 
00428 NSS_EXTERN NSSUTF8 *
00429 NSSATAV_GetValue
00430 (
00431   NSSATAV *atav,
00432   NSSArena *arenaOpt
00433 );
00434 
00435 extern const NSSError NSS_ERROR_INVALID_ATAV;
00436 extern const NSSError NSS_ERROR_NO_MEMORY;
00437 
00438 /*
00439  * NSSATAV_Compare
00440  *
00441  * This routine compares two ATAVs for equality.  For two ATAVs to be
00442  * equal, the attribute types must be the same, and the attribute 
00443  * values must have equal length and contents.  The result of the 
00444  * comparison will be stored at the location pointed to by the "equalp"
00445  * variable, which must point to a valid PRBool.  This routine may 
00446  * return PR_FAILURE upon error, in which case it will have created an
00447  * error stack.
00448  *
00449  * The error may be one of the following values:
00450  *  NSS_ERROR_INVALID_ATAV
00451  *  NSS_ERROR_INVALID_ARGUMENT
00452  *
00453  * Return value:
00454  *  PR_FAILURE on error
00455  *  PR_SUCCESS upon a successful comparison (equal or not)
00456  */
00457 
00458 NSS_EXTERN PRStatus
00459 NSSATAV_Compare
00460 (
00461   NSSATAV *atav1,
00462   NSSATAV *atav2,
00463   PRBool *equalp
00464 );
00465 
00466 extern const NSSError NSS_ERROR_INVALID_ATAV;
00467 extern const NSSError NSS_ERROR_INVALID_ARGUMENT;
00468 
00469 /*
00470  * NSSATAV_Duplicate
00471  *
00472  * This routine duplicates the specified ATAV.  If the optional arena 
00473  * argument is non-null, the memory required will be obtained from
00474  * that arena; otherwise, the memory will be obtained from the heap.  
00475  * This routine may return NULL upon error, in which case it will have 
00476  * created an error stack.
00477  *
00478  * The error may be one of the following values:
00479  *  NSS_ERROR_INVALID_ATAV
00480  *  NSS_ERROR_NO_MEMORY
00481  *
00482  * Return value:
00483  *  NULL on error
00484  *  A pointer to a new ATAV
00485  */
00486 
00487 NSS_EXTERN NSSATAV *
00488 NSSATAV_Duplicate
00489 (
00490   NSSATAV *atav,
00491   NSSArena *arenaOpt
00492 );
00493 
00494 extern const NSSError NSS_ERROR_INVALID_ATAV;
00495 extern const NSSError NSS_ERROR_NO_MEMORY;
00496 
00497 /*
00498  * NSSRDN
00499  *
00500  * The public "methods" regarding this "object" are:
00501  *
00502  *  NSSRDN_CreateFromBER   -- constructor
00503  *  NSSRDN_CreateFromUTF8  -- constructor
00504  *  NSSRDN_Create          -- constructor
00505  *  NSSRDN_CreateSimple    -- constructor
00506  *
00507  *  NSSRDN_Destroy
00508  *  NSSRDN_GetDEREncoding
00509  *  NSSRDN_GetUTF8Encoding
00510  *  NSSRDN_AddATAV
00511  *  NSSRDN_GetATAVCount
00512  *  NSSRDN_GetATAV
00513  *  NSSRDN_GetSimpleATAV
00514  *  NSSRDN_Compare
00515  *  NSSRDN_Duplicate
00516  */
00517 
00518 /*
00519  * NSSRDN_CreateFromBER
00520  *
00521  * This routine creates an NSSRDN by decoding a BER- or DER-encoded 
00522  * RDN.  If the optional arena argument is non-null, the memory used 
00523  * will be obtained from that arena; otherwise, the memory will be 
00524  * obtained from the heap.  This routine may return NULL upon error, 
00525  * in which case it will have created an error stack.
00526  *
00527  * The error may be one of the following values:
00528  *  NSS_ERROR_INVALID_BER
00529  *  NSS_ERROR_NO_MEMORY
00530  *
00531  * Return value:
00532  *  NULL upon error
00533  *  A pointer to an NSSRDN upon success
00534  */
00535 
00536 NSS_EXTERN NSSRDN *
00537 NSSRDN_CreateFromBER
00538 (
00539   NSSArena *arenaOpt,
00540   NSSBER *berRDN
00541 );
00542 
00543 /*
00544  * NSSRDN_CreateFromUTF8
00545  *
00546  * This routine creates an NSSRDN by decoding an UTF8 string 
00547  * consisting of either a single ATAV in the "equals" format, e.g., 
00548  * "uid=smith," or one or more such ATAVs in parentheses, e.g., 
00549  * "(sn=Smith,ou=Sales)."  If the optional arena argument is non-null,
00550  * the memory used will be obtained from that arena; otherwise, the
00551  * memory will be obtained from the heap.  This routine may return
00552  * NULL upon error, in which case it will have created an error stack.
00553  *
00554  * The error may be one of the following values:
00555  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
00556  *  NSS_ERROR_INVALID_STRING
00557  *  NSS_ERROR_NO_MEMORY
00558  *
00559  * Return value:
00560  *  NULL upon error
00561  *  A pointer to an NSSRDN upon success
00562  */
00563 
00564 NSS_EXTERN NSSRDN *
00565 NSSRDN_CreateFromUTF8
00566 (
00567   NSSArena *arenaOpt,
00568   NSSUTF8 *stringRDN
00569 );
00570 
00571 /*
00572  * NSSRDN_Create
00573  *
00574  * This routine creates an NSSRDN from one or more NSSATAVs.  The
00575  * final argument to this routine must be NULL.  If the optional arena
00576  * argument is non-null, the memory used will be obtained from that
00577  * arena; otherwise, the memory will be obtained from the heap.  This
00578  * routine may return NULL upon error, in which case it will have 
00579  * created an error stack.
00580  *
00581  * The error may be one of the following values:
00582  *  NSS_ERROR_NO_MEMORY
00583  *  NSS_ERROR_INVALID_ATAV
00584  *
00585  * Return value:
00586  *  NULL upon error
00587  *  A pointer to an NSSRDN upon success
00588  */
00589 
00590 NSS_EXTERN NSSRDN *
00591 NSSRDN_Create
00592 (
00593   NSSArena *arenaOpt,
00594   NSSATAV *atav1,
00595   ...
00596 );
00597 
00598 /*
00599  * NSSRDN_CreateSimple
00600  *
00601  * This routine creates a simple NSSRDN from a single NSSATAV.  If the
00602  * optional arena argument is non-null, the memory used will be 
00603  * obtained from that arena; otherwise, the memory will be obtained
00604  * from the heap.  This routine may return NULL upon error, in which
00605  * case it will have created an error stack.
00606  *
00607  * The error may be one of the following values:
00608  *  NSS_ERROR_NO_MEMORY
00609  *  NSS_ERROR_INVALID_ATAV
00610  *
00611  * Return value:
00612  *  NULL upon error
00613  *  A pointer to an NSSRDN upon success
00614  */
00615 
00616 NSS_EXTERN NSSRDN *
00617 NSSRDN_CreateSimple
00618 (
00619   NSSArena *arenaOpt,
00620   NSSATAV *atav
00621 );
00622 
00623 /*
00624  * NSSRDN_Destroy
00625  *
00626  * This routine will destroy an RDN object.  It should eventually be
00627  * called on all RDNs created without an arena.  While it is not 
00628  * necessary to call it on RDNs created within an arena, it is not an
00629  * error to do so.  This routine returns a PRStatus value; if
00630  * successful, it will return PR_SUCCESS.  If unsuccessful, it will 
00631  * create an error stack and return PR_FAILURE.
00632  *
00633  * The error may be one of the following values:
00634  *  NSS_ERROR_INVALID_RDN
00635  *
00636  * Return value:
00637  *  PR_FAILURE upon failure
00638  *  PR_SUCCESS upon success
00639  */
00640 
00641 NSS_EXTERN PRStatus
00642 NSSRDN_Destroy
00643 (
00644   NSSRDN *rdn
00645 );
00646 
00647 /*
00648  * NSSRDN_GetDEREncoding
00649  *
00650  * This routine will DER-encode an RDN object.  If the optional arena
00651  * argument is non-null, the memory used will be obtained from that
00652  * arena; otherwise, the memory will be obtained from the heap.  This
00653  * routine may return null upon error, in which case it will have 
00654  * created an error stack.
00655  *
00656  * The error may be one of the following values:
00657  *  NSS_ERROR_INVALID_RDN
00658  *  NSS_ERROR_NO_MEMORY
00659  *
00660  * Return value:
00661  *  NULL upon error
00662  *  The DER encoding of this NSSRDN
00663  */
00664 
00665 NSS_EXTERN NSSDER *
00666 NSSRDN_GetDEREncoding
00667 (
00668   NSSRDN *rdn,
00669   NSSArena *arenaOpt
00670 );
00671 
00672 /*
00673  * NSSRDN_GetUTF8Encoding
00674  *
00675  * This routine returns a UTF8 string containing a string 
00676  * representation of the RDN.  A simple (one-ATAV) RDN will be simply
00677  * the string representation of that ATAV; a non-simple RDN will be in
00678  * parenthesised form.  If the optional arena argument is non-null, 
00679  * the memory used will be obtained from that arena; otherwise, the 
00680  * memory will be obtained from the heap.  This routine may return 
00681  * null upon error, in which case it will have created an error stack.
00682  *
00683  * The error may be one of the following values:
00684  *  NSS_ERROR_INVALID_RDN
00685  *  NSS_ERROR_NO_MEMORY
00686  *
00687  * Return value:
00688  *  NULL upon error
00689  *  A pointer to a UTF8 string
00690  */
00691 
00692 NSS_EXTERN NSSUTF8 *
00693 NSSRDN_GetUTF8Encoding
00694 (
00695   NSSRDN *rdn,
00696   NSSArena *arenaOpt
00697 );
00698 
00699 /*
00700  * NSSRDN_AddATAV
00701  *
00702  * This routine adds an ATAV to the set of ATAVs in the specified RDN.
00703  * Remember that RDNs consist of an unordered set of ATAVs.  If the
00704  * RDN was created with a non-null arena argument, that same arena
00705  * will be used for any additional required memory.  If the RDN was 
00706  * created with a NULL arena argument, any additional memory will
00707  * be obtained from the heap.  This routine returns a PRStatus value;
00708  * it will return PR_SUCCESS upon success, and upon failure it will
00709  * create an error stack and return PR_FAILURE.
00710  *
00711  * The error may be one of the following values:
00712  *  NSS_ERROR_INVALID_RDN
00713  *  NSS_ERROR_INVALID_ATAV
00714  *  NSS_ERROR_NO_MEMORY
00715  *
00716  * Return value:
00717  *  PR_SUCCESS upon success
00718  *  PR_FAILURE upon failure
00719  */
00720 
00721 NSS_EXTERN PRStatus
00722 NSSRDN_AddATAV
00723 (
00724   NSSRDN *rdn,
00725   NSSATAV *atav
00726 );
00727 
00728 /*
00729  * NSSRDN_GetATAVCount
00730  *
00731  * This routine returns the cardinality of the set of ATAVs within
00732  * the specified RDN.  This routine may return 0 upon error, in which 
00733  * case it will have created an error stack.
00734  *
00735  * The error may be one of the following values:
00736  *  NSS_ERROR_INVALID_RDN
00737  *
00738  * Return value:
00739  *  0 upon error
00740  *  A positive number upon success
00741  */
00742 
00743 NSS_EXTERN PRUint32
00744 NSSRDN_GetATAVCount
00745 (
00746   NSSRDN *rdn
00747 );
00748 
00749 /*
00750  * NSSRDN_GetATAV
00751  *
00752  * This routine returns a pointer to an ATAV that is a member of
00753  * the set of ATAVs within the specified RDN.  While the set of
00754  * ATAVs within an RDN is unordered, this routine will return
00755  * distinct values for distinct values of 'i' as long as the RDN
00756  * is not changed in any way.  The RDN may be changed by calling
00757  * NSSRDN_AddATAV.  The value of the variable 'i' is on the range
00758  * [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount.
00759  * The caller owns the ATAV the pointer to which is returned.  If the
00760  * optional arena argument is non-null, the memory used will be 
00761  * obtained from that arena; otherwise, the memory will be obtained
00762  * from the heap.  This routine may return NULL upon error, in which 
00763  * case it will have created an error stack.
00764  *
00765  * The error may be one of the following values:
00766  *  NSS_ERROR_INVALID_RDN
00767  *  NSS_ERROR_VALUE_OUT_OF_RANGE
00768  *  NSS_ERROR_NO_MEMORY
00769  *
00770  * Return value:
00771  *  NULL upon error
00772  *  A caller-owned pointer to an NSSATAV
00773  */
00774 
00775 NSS_EXTERN NSSATAV *
00776 NSSRDN_GetATAV
00777 (
00778   NSSRDN *rdn,
00779   NSSArena *arenaOpt,
00780   PRUint32 i
00781 );
00782 
00783 /*
00784  * NSSRDN_GetSimpleATAV
00785  *
00786  * Most RDNs are actually very simple, with a single ATAV.  This 
00787  * routine will return the single ATAV from such an RDN.  The caller
00788  * owns the ATAV the pointer to which is returned.  If the optional
00789  * arena argument is non-null, the memory used will be obtained from
00790  * that arena; otherwise, the memory will be obtained from the heap.
00791  * This routine may return NULL upon error, including the case where
00792  * the set of ATAVs in the RDN is nonsingular.  Upon error, this
00793  * routine will have created an error stack.
00794  *
00795  * The error may be one of the following values:
00796  *  NSS_ERROR_INVALID_RDN
00797  *  NSS_ERROR_RDN_NOT_SIMPLE
00798  *  NSS_ERROR_NO_MEMORY
00799  *
00800  * Return value:
00801  *  NULL upon error
00802  *  A caller-owned pointer to an NSSATAV
00803  */
00804 
00805 NSS_EXTERN NSSATAV *
00806 NSSRDN_GetSimpleATAV
00807 (
00808   NSSRDN *rdn,
00809   NSSArena *arenaOpt
00810 );
00811 
00812 /*
00813  * NSSRDN_Compare
00814  *
00815  * This routine compares two RDNs for equality.  For two RDNs to be
00816  * equal, they must have the same number of ATAVs, and every ATAV in
00817  * one must be equal to an ATAV in the other.  (Note that the sets
00818  * of ATAVs are unordered.)  The result of the comparison will be
00819  * stored at the location pointed to by the "equalp" variable, which
00820  * must point to a valid PRBool.  This routine may return PR_FAILURE
00821  * upon error, in which case it will have created an error stack.
00822  *
00823  * The error may be one of the following values:
00824  *  NSS_ERROR_INVALID_RDN
00825  *  NSS_ERROR_INVALID_ARGUMENT
00826  *
00827  * Return value:
00828  *  PR_FAILURE on error
00829  *  PR_SUCCESS upon a successful comparison (equal or not)
00830  */
00831 
00832 NSS_EXTERN PRStatus
00833 NSSRDN_Compare
00834 (
00835   NSSRDN *rdn1,
00836   NSSRDN *rdn2,
00837   PRBool *equalp
00838 );
00839 
00840 /*
00841  * NSSRDN_Duplicate
00842  *
00843  * This routine duplicates the specified RDN.  If the optional arena
00844  * argument is non-null, the memory required will be obtained from
00845  * that arena; otherwise, the memory will be obtained from the heap.
00846  * This routine may return NULL upon error, in which case it will have
00847  * created an error stack.
00848  *
00849  * The error may be one of the following values:
00850  *  NSS_ERROR_INVALID_RDN
00851  *  NSS_ERROR_NO_MEMORY
00852  *
00853  * Return value:
00854  *  NULL on error
00855  *  A pointer to a new RDN
00856  */
00857 
00858 NSS_EXTERN NSSRDN *
00859 NSSRDN_Duplicate
00860 (
00861   NSSRDN *rdn,
00862   NSSArena *arenaOpt
00863 );
00864 
00865 /*
00866  * NSSRDNSeq
00867  *
00868  * The public "methods" regarding this "object" are:
00869  *
00870  *  NSSRDNSeq_CreateFromBER   -- constructor
00871  *  NSSRDNSeq_CreateFromUTF8  -- constructor
00872  *  NSSRDNSeq_Create          -- constructor
00873  *
00874  *  NSSRDNSeq_Destroy
00875  *  NSSRDNSeq_GetDEREncoding
00876  *  NSSRDNSeq_GetUTF8Encoding
00877  *  NSSRDNSeq_AppendRDN
00878  *  NSSRDNSeq_GetRDNCount
00879  *  NSSRDNSeq_GetRDN
00880  *  NSSRDNSeq_Compare
00881  *  NSSRDNSeq_Duplicate
00882  */
00883 
00884 /*
00885  * NSSRDNSeq_CreateFromBER
00886  *
00887  * This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded 
00888  * sequence of RDNs.  If the optional arena argument is non-null,
00889  * the memory used will be obtained from that arena; otherwise, the
00890  * memory will be obtained from the heap.  This routine may return 
00891  * NULL upon error, in which case it will have created an error stack.
00892  *
00893  * The error may be one of the following values:
00894  *  NSS_ERROR_INVALID_BER
00895  *  NSS_ERROR_NO_MEMORY
00896  *
00897  * Return value:
00898  *  NULL upon error
00899  *  A pointer to an NSSRDNSeq upon success
00900  */
00901 
00902 NSS_EXTERN NSSRDNSeq *
00903 NSSRDNSeq_CreateFromBER
00904 (
00905   NSSArena *arenaOpt,
00906   NSSBER *berRDNSeq
00907 );
00908 
00909 /*
00910  * NSSRDNSeq_CreateFromUTF8
00911  *
00912  * This routine creates an NSSRDNSeq by decoding a UTF8 string
00913  * consisting of a comma-separated sequence of RDNs, such as
00914  * "(sn=Smith,ou=Sales),o=Acme,c=US."  If the optional arena argument
00915  * is non-null, the memory used will be obtained from that arena; 
00916  * otherwise, the memory will be obtained from the heap.  This routine
00917  * may return NULL upon error, in which case it will have created an
00918  * error stack.
00919  *
00920  * The error may be one of the following values:
00921  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
00922  *  NSS_ERROR_INVALID_STRING
00923  *  NSS_ERROR_NO_MEMORY
00924  *
00925  * Return value:
00926  *  NULL upon error
00927  *  A pointer to an NSSRDNSeq upon success
00928  */
00929 
00930 NSS_EXTERN NSSRDNSeq *
00931 NSSRDNSeq_CreateFromUTF8
00932 (
00933   NSSArena *arenaOpt,
00934   NSSUTF8 *stringRDNSeq
00935 );
00936 
00937 /*
00938  * NSSRDNSeq_Create
00939  *
00940  * This routine creates an NSSRDNSeq from one or more NSSRDNs.  The
00941  * final argument to this routine must be NULL.  If the optional arena
00942  * argument is non-null, the memory used will be obtained from that
00943  * arena; otherwise, the memory will be obtained from the heap.  This
00944  * routine may return NULL upon error, in which case it will have
00945  * created an error stack.
00946  *
00947  * The error may be one of the following values:
00948  *  NSS_ERROR_NO_MEMORY
00949  *  NSS_ERROR_INVALID_RDN
00950  *
00951  * Return value:
00952  *  NULL upon error
00953  *  A pointero to an NSSRDNSeq upon success
00954  */
00955 
00956 NSS_EXTERN NSSRDNSeq *
00957 NSSRDNSeq_Create
00958 (
00959   NSSArena *arenaOpt,
00960   NSSRDN *rdn1,
00961   ...
00962 );
00963 
00964 /*
00965  * NSSRDNSeq_Destroy
00966  *
00967  * This routine will destroy an RDNSeq object.  It should eventually 
00968  * be called on all RDNSeqs created without an arena.  While it is not
00969  * necessary to call it on RDNSeqs created within an arena, it is not
00970  * an error to do so.  This routine returns a PRStatus value; if
00971  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
00972  * create an error stack and return PR_FAILURE.
00973  *
00974  * The error may be one of the following values:
00975  *  NSS_ERROR_INVALID_RDNSEQ
00976  *
00977  * Return value:
00978  *  PR_FAILURE upon error
00979  *  PR_SUCCESS upon success
00980  */
00981 
00982 NSS_EXTERN PRStatus
00983 NSSRDNSeq_Destroy
00984 (
00985   NSSRDNSeq *rdnseq
00986 );
00987 
00988 /*
00989  * NSSRDNSeq_GetDEREncoding
00990  *
00991  * This routine will DER-encode an RDNSeq object.  If the optional 
00992  * arena argument is non-null, the memory used will be obtained from
00993  * that arena; otherwise, the memory will be obtained from the heap.
00994  * This routine may return null upon error, in which case it will have
00995  * created an error stack.
00996  *
00997  * The error may be one of the following values:
00998  *  NSS_ERROR_INVALID_RDNSEQ
00999  *  NSS_ERROR_NO_MEMORY
01000  *
01001  * Return value:
01002  *  NULL upon error
01003  *  The DER encoding of this NSSRDNSeq
01004  */
01005 
01006 NSS_EXTERN NSSDER *
01007 NSSRDNSeq_GetDEREncoding
01008 (
01009   NSSRDNSeq *rdnseq,
01010   NSSArena *arenaOpt
01011 );
01012 
01013 /*
01014  * NSSRDNSeq_GetUTF8Encoding
01015  *
01016  * This routine returns a UTF8 string containing a string 
01017  * representation of the RDNSeq as a comma-separated sequence of RDNs.  
01018  * If the optional arena argument is non-null, the memory used will be
01019  * obtained from that arena; otherwise, the memory will be obtained 
01020  * from the heap.  This routine may return null upon error, in which 
01021  * case it will have created an error stack.
01022  *
01023  * The error may be one of the following values:
01024  *  NSS_ERROR_INVALID_RDNSEQ
01025  *  NSS_ERROR_NO_MEMORY
01026  *
01027  * Return value:
01028  *  NULL upon error
01029  *  A pointer to the UTF8 string
01030  */
01031 
01032 NSS_EXTERN NSSUTF8 *
01033 NSSRDNSeq_GetUTF8Encoding
01034 (
01035   NSSRDNSeq *rdnseq,
01036   NSSArena *arenaOpt
01037 );
01038 
01039 /*
01040  * NSSRDNSeq_AppendRDN
01041  *
01042  * This routine appends an RDN to the end of the existing RDN 
01043  * sequence.  If the RDNSeq was created with a non-null arena 
01044  * argument, that same arena will be used for any additional required
01045  * memory.  If the RDNSeq was created with a NULL arena argument, any
01046  * additional memory will be obtained from the heap.  This routine
01047  * returns a PRStatus value; it will return PR_SUCCESS upon success,
01048  * and upon failure it will create an error stack and return PR_FAILURE.
01049  *
01050  * The error may be one of the following values:
01051  *  NSS_ERROR_INVALID_RDNSEQ
01052  *  NSS_ERROR_INVALID_RDN
01053  *  NSS_ERROR_NO_MEMORY
01054  *
01055  * Return value:
01056  *  PR_SUCCESS upon success
01057  *  PR_FAILURE upon failure
01058  */
01059 
01060 NSS_EXTERN PRStatus
01061 NSSRDNSeq_AppendRDN
01062 (
01063   NSSRDNSeq *rdnseq,
01064   NSSRDN *rdn
01065 );
01066 
01067 /*
01068  * NSSRDNSeq_GetRDNCount
01069  *
01070  * This routine returns the cardinality of the sequence of RDNs within
01071  * the specified RDNSeq.  This routine may return 0 upon error, in 
01072  * which case it will have created an error stack.
01073  *
01074  * The error may be one of the following values:
01075  *  NSS_ERROR_INVALID_RDNSEQ
01076  *
01077  * Return value:
01078  *  0 upon error
01079  *  A positive number upon success
01080  */
01081 
01082 NSS_EXTERN PRUint32
01083 NSSRDNSeq_GetRDNCount
01084 (
01085   NSSRDNSeq *rdnseq
01086 );
01087 
01088 /*
01089  * NSSRDNSeq_GetRDN
01090  *
01091  * This routine returns a pointer to the i'th RDN in the sequence of
01092  * RDNs that make up the specified RDNSeq.  The sequence begins with
01093  * the top-level (e.g., "c=US") RDN.  The value of the variable 'i'
01094  * is on the range [0,c) where c is the cardinality returned from
01095  * NSSRDNSeq_GetRDNCount.  The caller owns the RDN the pointer to which
01096  * is returned.  If the optional arena argument is non-null, the memory
01097  * used will be obtained from that areana; otherwise, the memory will 
01098  * be obtained from the heap.  This routine may return NULL upon error,
01099  * in which case it will have created an error stack.  Note that the 
01100  * usual string representation of RDN Sequences is from last to first.
01101  *
01102  * The error may be one of the following values:
01103  *  NSS_ERROR_INVALID_RDNSEQ
01104  *  NSS_ERROR_VALUE_OUT_OF_RANGE
01105  *  NSS_ERROR_NO_MEMORY
01106  *
01107  * Return value:
01108  *  NULL upon error
01109  *  A caller-owned pointer to an NSSRDN
01110  */
01111 
01112 NSS_EXTERN NSSRDN *
01113 NSSRDNSeq_GetRDN
01114 (
01115   NSSRDNSeq *rdnseq,
01116   NSSArena *arenaOpt,
01117   PRUint32 i
01118 );
01119 
01120 /*
01121  * NSSRDNSeq_Compare
01122  *
01123  * This routine compares two RDNSeqs for equality.  For two RDNSeqs to 
01124  * be equal, they must have the same number of RDNs, and each RDN in
01125  * one sequence must be equal to the corresponding RDN in the other
01126  * sequence.  The result of the comparison will be stored at the
01127  * location pointed to by the "equalp" variable, which must point to a
01128  * valid PRBool.  This routine may return PR_FAILURE upon error, in
01129  * which case it will have created an error stack.
01130  *
01131  * The error may be one of the following values:
01132  *  NSS_ERROR_INVALID_RDNSEQ
01133  *  NSS_ERROR_INVALID_ARGUMENT
01134  *
01135  * Return value:
01136  *  PR_FAILURE on error
01137  *  PR_SUCCESS upon a successful comparison (equal or not)
01138  */
01139 
01140 NSS_EXTERN PRStatus
01141 NSSRDNSeq_Compare
01142 (
01143   NSSRDNSeq *rdnseq1,
01144   NSSRDNSeq *rdnseq2,
01145   PRBool *equalp
01146 );
01147 
01148 /*
01149  * NSSRDNSeq_Duplicate
01150  *
01151  * This routine duplicates the specified RDNSeq.  If the optional arena
01152  * argument is non-null, the memory required will be obtained from that
01153  * arena; otherwise, the memory will be obtained from the heap.  This 
01154  * routine may return NULL upon error, in which case it will have 
01155  * created an error stack.
01156  *
01157  * The error may be one of the following values:
01158  *  NSS_ERROR_INVALID_RDNSEQ
01159  *  NSS_ERROR_NO_MEMORY
01160  *
01161  * Return value:
01162  *  NULL upon error
01163  *  A pointer to a new RDNSeq
01164  */
01165 
01166 NSS_EXTERN NSSRDNSeq *
01167 NSSRDNSeq_Duplicate
01168 (
01169   NSSRDNSeq *rdnseq,
01170   NSSArena *arenaOpt
01171 );
01172 
01173 /*
01174  * NSSName
01175  *
01176  * The public "methods" regarding this "object" are:
01177  *
01178  * NSSName_CreateFromBER   -- constructor
01179  * NSSName_CreateFromUTF8  -- constructor
01180  * NSSName_Create          -- constructor
01181  *
01182  * NSSName_Destroy
01183  * NSSName_GetDEREncoding
01184  * NSSName_GetUTF8Encoding
01185  * NSSName_GetChoice
01186  * NSSName_GetRDNSequence
01187  * NSSName_GetSpecifiedChoice
01188  * NSSName_Compare
01189  * NSSName_Duplicate
01190  *
01191  * NSSName_GetUID
01192  * NSSName_GetEmail
01193  * NSSName_GetCommonName
01194  * NSSName_GetOrganization
01195  * NSSName_GetOrganizationalUnits
01196  * NSSName_GetStateOrProvince
01197  * NSSName_GetLocality
01198  * NSSName_GetCountry
01199  * NSSName_GetAttribute
01200  */
01201 
01202 /*
01203  * NSSName_CreateFromBER
01204  *
01205  * This routine creates an NSSName by decoding a BER- or DER-encoded 
01206  * (directory) Name.  If the optional arena argument is non-null,
01207  * the memory used will be obtained from that arena; otherwise, 
01208  * the memory will be obtained from the heap.  This routine may
01209  * return NULL upon error, in which case it will have created an error
01210  * stack.
01211  *
01212  * The error may be one of the following values:
01213  *  NSS_ERROR_INVALID_BER
01214  *  NSS_ERROR_NO_MEMORY
01215  *
01216  * Return value:
01217  *  NULL upon error
01218  *  A pointer to an NSSName upon success
01219  */
01220 
01221 NSS_EXTERN NSSName *
01222 NSSName_CreateFromBER
01223 (
01224   NSSArena *arenaOpt,
01225   NSSBER *berName
01226 );
01227 
01228 /*
01229  * NSSName_CreateFromUTF8
01230  *
01231  * This routine creates an NSSName by decoding a UTF8 string 
01232  * consisting of the string representation of one of the choices of 
01233  * (directory) names.  Currently the only choice is an RDNSeq.  If the
01234  * optional arena argument is non-null, the memory used will be 
01235  * obtained from that arena; otherwise, the memory will be obtained 
01236  * from the heap.  The routine may return NULL upon error, in which
01237  * case it will have created an error stack.
01238  *
01239  * The error may be one of the following values:
01240  *  NSS_ERROR_INVALID_STRING
01241  *  NSS_ERROR_NO_MEMORY
01242  *
01243  * Return value:
01244  *  NULL upon error
01245  *  A pointer to an NSSName upon success
01246  */
01247 
01248 NSS_EXTERN NSSName *
01249 NSSName_CreateFromUTF8
01250 (
01251   NSSArena *arenaOpt,
01252   NSSUTF8 *stringName
01253 );
01254 
01255 /*
01256  * NSSName_Create
01257  *
01258  * This routine creates an NSSName with the specified choice of
01259  * underlying name types.  The value of the choice variable must be
01260  * one of the values of the NSSNameChoice enumeration, and the type
01261  * of the arg variable must be as specified in the following table:
01262  *
01263  *   Choice                     Type
01264  *   ========================   ===========
01265  *   NSSNameChoiceRdnSequence   NSSRDNSeq *
01266  *
01267  * If the optional arena argument is non-null, the memory used will
01268  * be obtained from that arena; otherwise, the memory will be 
01269  * obtained from the heap.  This routine may return NULL upon error,
01270  * in which case it will have created an error stack.
01271  *
01272  * The error may be one of the following values:
01273  *  NSS_ERROR_INVALID_CHOICE
01274  *  NSS_ERROR_INVALID_ARGUMENT
01275  *  NSS_ERROR_NO_MEMORY
01276  *
01277  * Return value:
01278  *  NULL upon error
01279  *  A pointer to an NSSName upon success
01280  */
01281 
01282 NSS_EXTERN NSSName *
01283 NSSName_Create
01284 (
01285   NSSArena *arenaOpt,
01286   NSSNameChoice choice,
01287   void *arg
01288 );
01289 
01290 /*
01291  * NSSName_Destroy
01292  *
01293  * This routine will destroy a Name object.  It should eventually be
01294  * called on all Names created without an arena.  While it is not
01295  * necessary to call it on Names created within an arena, it is not
01296  * an error to do so.  This routine returns a PRStatus value; if
01297  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
01298  * create an error stack and return PR_FAILURE.
01299  *
01300  * The error may be one of the following values:
01301  *  NSS_ERROR_INVALID_NAME
01302  *
01303  * Return value:
01304  *  PR_FAILURE upon error
01305  *  PR_SUCCESS upon success
01306  */
01307 
01308 NSS_EXTERN PRStatus
01309 NSSName_Destroy
01310 (
01311   NSSName *name
01312 );
01313 
01314 /*
01315  * NSSName_GetDEREncoding
01316  *
01317  * This routine will DER-encode a name object.  If the optional arena
01318  * argument is non-null, the memory used will be obtained from that
01319  * arena; otherwise, the memory will be obtained from the heap.  This
01320  * routine may return null upon error, in which case it will have 
01321  * created an error stack.
01322  *
01323  * The error may be one of the following values:
01324  *  NSS_ERROR_INVALID_NAME
01325  *  NSS_ERROR_NO_MEMORY
01326  *
01327  * Return value:
01328  *  NULL upon error
01329  *  The DER encoding of this NSSName
01330  */
01331 
01332 NSS_EXTERN NSSDER *
01333 NSSName_GetDEREncoding
01334 (
01335   NSSName *name,
01336   NSSArena *arenaOpt
01337 );
01338 
01339 /*
01340  * NSSName_GetUTF8Encoding
01341  *
01342  * This routine returns a UTF8 string containing a string 
01343  * representation of the Name in the format specified by the 
01344  * underlying name choice.  If the optional arena argument is non-null,
01345  * the memory used will be obtained from that arena; otherwise, the 
01346  * memory will be obtained from the heap.  This routine may return
01347  * NULL upon error, in which case it will have created an error stack.
01348  *
01349  * The error may be one of the following values:
01350  *  NSS_ERROR_INVALID_NAME
01351  *  NSS_ERROR_NO_MEMORY
01352  *
01353  * Return value:
01354  *  NULL upon error
01355  *  A pointer to the UTF8 string
01356  */
01357 
01358 NSS_EXTERN NSSUTF8 *
01359 NSSName_GetUTF8Encoding
01360 (
01361   NSSName *name,
01362   NSSArena *arenaOpt
01363 );
01364 
01365 /*
01366  * NSSName_GetChoice
01367  *
01368  * This routine returns the type of the choice underlying the specified
01369  * name.  The return value will be a member of the NSSNameChoice 
01370  * enumeration.  This routine may return NSSNameChoiceInvalid upon 
01371  * error, in which case it will have created an error stack.
01372  *
01373  * The error may be one of the following values:
01374  *  NSS_ERROR_INVALID_NAME
01375  *
01376  * Return value:
01377  *  NSSNameChoiceInvalid upon error
01378  *  An other member of the NSSNameChoice enumeration upon success
01379  */
01380 
01381 NSS_EXTERN NSSNameChoice
01382 NSSName_GetChoice
01383 (
01384   NSSName *name
01385 );
01386 
01387 /*
01388  * NSSName_GetRDNSequence
01389  *
01390  * If the choice underlying the specified NSSName is that of an 
01391  * RDNSequence, this routine will return a pointer to that RDN
01392  * sequence.  Otherwise, this routine will place an error on the
01393  * error stack, and return NULL.  If the optional arena argument is
01394  * non-null, the memory required will be obtained from that arena;
01395  * otherwise, the memory will be obtained from the heap.  The
01396  * caller owns the returned pointer.  This routine may return NULL
01397  * upon error, in which case it will have created an error stack.
01398  *
01399  * The error may be one of the following values:
01400  *  NSS_ERROR_INVALID_NAME
01401  *  NSS_ERROR_WRONG_CHOICE
01402  *  NSS_ERROR_NO_MEMORY
01403  *
01404  * Return value:
01405  *  NULL upon error
01406  *  A caller-owned pointer to an NSSRDNSeq
01407  */
01408 
01409 NSS_EXTERN NSSRDNSeq *
01410 NSSName_GetRDNSequence
01411 (
01412   NSSName *name,
01413   NSSArena *arenaOpt
01414 );
01415 
01416 /*
01417  * NSSName_GetSpecifiedChoice
01418  *
01419  * If the choice underlying the specified NSSName matches the specified
01420  * choice, a caller-owned pointer to that underlying object will be
01421  * returned.  Otherwise, an error will be placed on the error stack and
01422  * NULL will be returned.  If the optional arena argument is non-null, 
01423  * the memory required will be obtained from that arena; otherwise, the
01424  * memory will be obtained from the heap.  The caller owns the returned
01425  * pointer.  This routine may return NULL upon error, in which case it
01426  * will have created an error stack.
01427  *
01428  * The error may be one of the following values:
01429  *  NSS_ERROR_INVALID_NAME
01430  *  NSS_ERROR_WRONG_CHOICE
01431  *  NSS_ERROR_NO_MEMORY
01432  *
01433  * Return value:
01434  *  NULL upon error
01435  *  A caller-owned pointer, which must be typecast
01436  */
01437 
01438 NSS_EXTERN void *
01439 NSSName_GetSpecifiedChoice
01440 (
01441   NSSName *name,
01442   NSSNameChoice choice,
01443   NSSArena *arenaOpt
01444 );
01445 
01446 /*
01447  * NSSName_Compare
01448  *
01449  * This routine compares two Names for equality.  For two Names to be
01450  * equal, they must have the same choice of underlying types, and the
01451  * underlying values must be equal.  The result of the comparison will
01452  * be stored at the location pointed to by the "equalp" variable, which
01453  * must point to a valid PRBool. This routine may return PR_FAILURE
01454  * upon error, in which case it will have created an error stack.
01455  *
01456  * The error may be one of the following values:
01457  *  NSS_ERROR_INVALID_NAME
01458  *  NSS_ERROR_INVALID_ARGUMENT
01459  *
01460  * Return value:
01461  *  PR_FAILURE on error
01462  *  PR_SUCCESS upon a successful comparison (equal or not)
01463  */
01464 
01465 NSS_EXTERN PRStatus
01466 NSSName_Compare
01467 (
01468   NSSName *name1,
01469   NSSName *name2,
01470   PRBool *equalp
01471 );
01472 
01473 /*
01474  * NSSName_Duplicate
01475  *
01476  * This routine duplicates the specified nssname.  If the optional
01477  * arena argument is non-null, the memory required will be obtained
01478  * from that arena; otherwise, the memory will be obtained from the
01479  * heap.  This routine may return NULL upon error, in which case it
01480  * will have created an error stack.
01481  *
01482  * The error may be one of the following values:
01483  *  NSS_ERROR_INVALID_NAME
01484  *  NSS_ERROR_NO_MEMORY
01485  *
01486  * Return value:
01487  *  NULL upon error
01488  *  A pointer to a new NSSName
01489  */
01490 
01491 NSS_EXTERN NSSName *
01492 NSSName_Duplicate
01493 (
01494   NSSName *name,
01495   NSSArena *arenaOpt
01496 );
01497 
01498 /*
01499  * NSSName_GetUID
01500  *
01501  * This routine will attempt to derive a user identifier from the
01502  * specified name, if the choices and content of the name permit.
01503  * If the Name consists of a Sequence of Relative Distinguished 
01504  * Names containing a UID attribute, the UID will be the value of 
01505  * that attribute.  Note that no UID attribute is defined in either 
01506  * PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which 
01507  * defines the type as a caseIgnoreString.  We'll return a Directory 
01508  * String.  If the optional arena argument is non-null, the memory 
01509  * used will be obtained from that arena; otherwise, the memory will 
01510  * be obtained from the heap.  This routine may return NULL upon error,
01511  * in which case it will have created an error stack.
01512  *
01513  * The error may be one of the following values:
01514  *  NSS_ERROR_INVALID_NAME
01515  *  NSS_ERROR_NO_UID
01516  *  NSS_ERROR_NO_MEMORY
01517  *
01518  * Return value:
01519  *  NULL upon error
01520  *  A pointer to a UTF8 String.
01521  */
01522 
01523 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01524 NSSName_GetUID
01525 (
01526   NSSName *name,
01527   NSSArena *arenaOpt
01528 );
01529 
01530 /*
01531  * NSSName_GetEmail
01532  *
01533  * This routine will attempt to derive an email address from the
01534  * specified name, if the choices and content of the name permit.  
01535  * If the Name consists of a Sequence of Relative Distinguished 
01536  * Names containing either a PKIX email address or a PKCS#9 email
01537  * address, the result will be the value of that attribute.  If the
01538  * optional arena argument is non-null, the memory used will be
01539  * obtained from that arena; otherwise, the memory will be obtained
01540  * from the heap.  This routine may return NULL upon error, in which
01541  * case it will have created an error stack.
01542  *
01543  * The error may be one of the following values:
01544  *  NSS_ERROR_INVALID_NAME
01545  *  NSS_ERROR_NO_EMAIL
01546  *  NSS_ERROR_NO_MEMORY
01547  *
01548  * Return value:
01549  *  NULL upon error
01550  *  A pointer to a UTF8 String
01551  */
01552 
01553 NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5 String */
01554 NSSName_GetEmail
01555 (
01556   NSSName *name,
01557   NSSArena *arenaOpt
01558 );
01559 
01560 /*
01561  * NSSName_GetCommonName
01562  *
01563  * This routine will attempt to derive a common name from the
01564  * specified name, if the choices and content of the name permit.  
01565  * If the Name consists of a Sequence of Relative Distinguished Names
01566  * containing a PKIX Common Name, the result will be that name.  If 
01567  * the optional arena argument is non-null, the memory used will be 
01568  * obtained from that arena; otherwise, the memory will be obtained 
01569  * from the heap.  This routine may return NULL upon error, in which 
01570  * case it will have created an error stack.
01571  *
01572  * The error may be one of the following values:
01573  *  NSS_ERROR_INVALID_NAME
01574  *  NSS_ERROR_NO_COMMON_NAME
01575  *  NSS_ERROR_NO_MEMORY
01576  *
01577  * Return value:
01578  *  NULL upon error
01579  *  A pointer to a UTF8 String
01580  */
01581 
01582 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01583 NSSName_GetCommonName
01584 (
01585   NSSName *name,
01586   NSSArena *arenaOpt
01587 );
01588 
01589 /*
01590  * NSSName_GetOrganization
01591  *
01592  * This routine will attempt to derive an organisation name from the
01593  * specified name, if the choices and content of the name permit.  
01594  * If Name consists of a Sequence of Relative Distinguished names 
01595  * containing a PKIX Organization, the result will be the value of 
01596  * that attribute.  If the optional arena argument is non-null, the 
01597  * memory used will be obtained from that arena; otherwise, the memory 
01598  * will be obtained from the heap.  This routine may return NULL upon 
01599  * error, in which case it will have created an error stack.
01600  *
01601  * The error may be one of the following values:
01602  *  NSS_ERROR_INVALID_NAME
01603  *  NSS_ERROR_NO_ORGANIZATION
01604  *  NSS_ERROR_NO_MEMORY
01605  *
01606  * Return value:
01607  *  NULL upon error
01608  *  A pointer to a UTF8 String
01609  */
01610 
01611 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01612 NSSName_GetOrganization
01613 (
01614   NSSName *name,
01615   NSSArena *arenaOpt
01616 );
01617 
01618 /*
01619  * NSSName_GetOrganizationalUnits
01620  *
01621  * This routine will attempt to derive a sequence of organisational 
01622  * unit names from the specified name, if the choices and content of 
01623  * the name permit.  If the Name consists of a Sequence of Relative 
01624  * Distinguished Names containing one or more organisational units,
01625  * the result will be the values of those attributes.  If the optional 
01626  * arena argument is non-null, the memory used will be obtained from 
01627  * that arena; otherwise, the memory will be obtained from the heap.  
01628  * This routine may return NULL upon error, in which case it will have 
01629  * created an error stack.
01630  *
01631  * The error may be one of the following values:
01632  *  NSS_ERROR_INVALID_NAME
01633  *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
01634  *  NSS_ERROR_NO_MEMORY
01635  *
01636  * Return value:
01637  *  NULL upon error
01638  *  A pointer to a null-terminated array of UTF8 Strings
01639  */
01640 
01641 NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
01642 NSSName_GetOrganizationalUnits
01643 (
01644   NSSName *name,
01645   NSSArena *arenaOpt
01646 );
01647 
01648 /*
01649  * NSSName_GetStateOrProvince
01650  *
01651  * This routine will attempt to derive a state or province name from 
01652  * the specified name, if the choices and content of the name permit.
01653  * If the Name consists of a Sequence of Relative Distinguished Names
01654  * containing a state or province, the result will be the value of 
01655  * that attribute.  If the optional arena argument is non-null, the 
01656  * memory used will be obtained from that arena; otherwise, the memory 
01657  * will be obtained from the heap.  This routine may return NULL upon 
01658  * error, in which case it will have created an error stack.
01659  *
01660  * The error may be one of the following values:
01661  *  NSS_ERROR_INVALID_NAME
01662  *  NSS_ERROR_NO_STATE_OR_PROVINCE
01663  *  NSS_ERROR_NO_MEMORY
01664  *
01665  * Return value:
01666  *  NULL upon error
01667  *  A pointer to a UTF8 String
01668  */
01669 
01670 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01671 NSSName_GetStateOrProvince
01672 (
01673   NSSName *name,
01674   NSSArena *arenaOpt
01675 );
01676 
01677 /*
01678  * NSSName_GetLocality
01679  *
01680  * This routine will attempt to derive a locality name from the 
01681  * specified name, if the choices and content of the name permit.  If
01682  * the Name consists of a Sequence of Relative Distinguished names
01683  * containing a Locality, the result will be the value of that 
01684  * attribute.  If the optional arena argument is non-null, the memory 
01685  * used will be obtained from that arena; otherwise, the memory will 
01686  * be obtained from the heap.  This routine may return NULL upon error,
01687  * in which case it will have created an error stack.
01688  *
01689  * The error may be one of the following values:
01690  *  NSS_ERROR_INVALID_NAME
01691  *  NSS_ERROR_NO_LOCALITY
01692  *  NSS_ERROR_NO_MEMORY
01693  *
01694  * Return value:
01695  *  NULL upon error
01696  *  A pointer to a UTF8 String
01697  */
01698 
01699 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01700 NSSName_GetLocality
01701 (
01702   NSSName *name,
01703   NSSArena *arenaOpt
01704 );
01705 
01706 /*
01707  * NSSName_GetCountry
01708  *
01709  * This routine will attempt to derive a country name from the 
01710  * specified name, if the choices and content of the name permit.
01711  * If the Name consists of a Sequence of Relative Distinguished 
01712  * Names containing a Country, the result will be the value of
01713  * that attribute..  If the optional arena argument is non-null, 
01714  * the memory used will be obtained from that arena; otherwise, 
01715  * the memory will be obtained from the heap.  This routine may 
01716  * return NULL upon error, in which case it will have created an 
01717  * error stack.
01718  *
01719  * The error may be one of the following values:
01720  *  NSS_ERROR_INVALID_NAME
01721  *  NSS_ERROR_NO_COUNTRY
01722  *  NSS_ERROR_NO_MEMORY
01723  *
01724  * Return value:
01725  *  NULL upon error
01726  *  A pointer to a UTF8 String
01727  */
01728 
01729 NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
01730 NSSName_GetCountry
01731 (
01732   NSSName *name,
01733   NSSArena *arenaOpt
01734 );
01735 
01736 /*
01737  * NSSName_GetAttribute
01738  *
01739  * If the specified name consists of a Sequence of Relative 
01740  * Distinguished Names containing an attribute with the specified 
01741  * type, and the actual value of that attribute may be expressed 
01742  * with a Directory String, then the value of that attribute will 
01743  * be returned as a Directory String.  If the optional arena argument 
01744  * is non-null, the memory used will be obtained from that arena; 
01745  * otherwise, the memory will be obtained from the heap.  This routine 
01746  * may return NULL upon error, in which case it will have created an
01747  * error stack.
01748  *
01749  * The error may be one of the following values:
01750  *  NSS_ERROR_INVALID_NAME
01751  *  NSS_ERROR_NO_ATTRIBUTE
01752  *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
01753  *
01754  * Return value:
01755  *  NULL upon error
01756  *  A pointer to a UTF8 String
01757  */
01758 
01759 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01760 NSSName_GetAttribute
01761 (
01762   NSSName *name,
01763   NSSOID *attribute,
01764   NSSArena *arenaOpt
01765 );
01766 
01767 /*
01768  * NSSGeneralName
01769  *
01770  * The public "methods" regarding this "object" are:
01771  *
01772  * NSSGeneralName_CreateFromBER   -- constructor
01773  * NSSGeneralName_CreateFromUTF8  -- constructor
01774  * NSSGeneralName_Create          -- constructor
01775  *
01776  * NSSGeneralName_Destroy
01777  * NSSGeneralName_GetDEREncoding
01778  * NSSGeneralName_GetUTF8Encoding
01779  * NSSGeneralName_GetChoice
01780  * NSSGeneralName_GetOtherName
01781  * NSSGeneralName_GetRfc822Name
01782  * NSSGeneralName_GetDNSName
01783  * NSSGeneralName_GetX400Address
01784  * NSSGeneralName_GetDirectoryName
01785  * NSSGeneralName_GetEdiPartyName
01786  * NSSGeneralName_GetUniformResourceIdentifier
01787  * NSSGeneralName_GetIPAddress
01788  * NSSGeneralName_GetRegisteredID
01789  * NSSGeneralName_GetSpecifiedChoice
01790  * NSSGeneralName_Compare
01791  * NSSGeneralName_Duplicate
01792  *
01793  * NSSGeneralName_GetUID
01794  * NSSGeneralName_GetEmail
01795  * NSSGeneralName_GetCommonName
01796  * NSSGeneralName_GetOrganization
01797  * NSSGeneralName_GetOrganizationalUnits
01798  * NSSGeneralName_GetStateOrProvince
01799  * NSSGeneralName_GetLocality
01800  * NSSGeneralName_GetCountry
01801  * NSSGeneralName_GetAttribute
01802  */
01803 
01804 /*
01805  * NSSGeneralName_CreateFromBER
01806  *
01807  * This routine creates an NSSGeneralName by decoding a BER- or DER-
01808  * encoded general name.  If the optional arena argument is non-null,
01809  * the memory used will be obtained from that arena; otherwise, the 
01810  * memory will be obtained from the heap.  This routine may return 
01811  * NULL upon error, in which case it will have created an error stack.
01812  *
01813  * The error may be one of the following values:
01814  *  NSS_ERROR_INVALID_BER
01815  *  NSS_ERROR_NO_MEMORY
01816  *
01817  * Return value:
01818  *  NULL upon error
01819  *  A pointer to an NSSGeneralName upon success
01820  */
01821 
01822 NSS_EXTERN NSSGeneralName *
01823 NSSGeneralName_CreateFromBER
01824 (
01825   NSSArena *arenaOpt,
01826   NSSBER *berGeneralName
01827 );
01828 
01829 /*
01830  * NSSGeneralName_CreateFromUTF8
01831  *
01832  * This routine creates an NSSGeneralName by decoding a UTF8 string
01833  * consisting of the string representation of one of the choices of
01834  * general names.  If the optional arena argument is non-null, the 
01835  * memory used will be obtained from that arena; otherwise, the memory
01836  * will be obtained from the heap.  The routine may return NULL upon
01837  * error, in which case it will have created an error stack.
01838  *
01839  * The error may be one of the following values:
01840  *  NSS_ERROR_INVALID_STRING
01841  *  NSS_ERROR_NO_MEMORY
01842  *
01843  * Return value:
01844  *  NULL upon error
01845  *  A pointer to an NSSGeneralName upon success
01846  */
01847 
01848 NSS_EXTERN NSSGeneralName *
01849 NSSGeneralName_CreateFromUTF8
01850 (
01851   NSSArena *arenaOpt,
01852   NSSUTF8 *stringGeneralName
01853 );
01854 
01855 /*
01856  * NSSGeneralName_Create
01857  *
01858  * This routine creates an NSSGeneralName with the specified choice of
01859  * underlying name types.  The value of the choice variable must be one
01860  * of the values of the NSSGeneralNameChoice enumeration, and the type
01861  * of the arg variable must be as specified in the following table:
01862  *
01863  *   Choice                                         Type
01864  *   ============================================   =========
01865  *   NSSGeneralNameChoiceOtherName
01866  *   NSSGeneralNameChoiceRfc822Name
01867  *   NSSGeneralNameChoiceDNSName
01868  *   NSSGeneralNameChoiceX400Address
01869  *   NSSGeneralNameChoiceDirectoryName              NSSName *
01870  *   NSSGeneralNameChoiceEdiPartyName
01871  *   NSSGeneralNameChoiceUniformResourceIdentifier
01872  *   NSSGeneralNameChoiceIPAddress
01873  *   NSSGeneralNameChoiceRegisteredID
01874  *
01875  * If the optional arena argument is non-null, the memory used will
01876  * be obtained from that arena; otherwise, the memory will be 
01877  * obtained from the heap.  This routine may return NULL upon error,
01878  * in which case it will have created an error stack.
01879  *
01880  * The error may be one fo the following values:
01881  *  NSS_ERROR_INVALID_CHOICE
01882  *  NSS_ERROR_INVALID_ARGUMENT
01883  *  NSS_ERROR_NO_MEMORY
01884  *
01885  * Return value:
01886  *  NULL upon error
01887  *  A pointer to an NSSGeneralName upon success
01888  */
01889 
01890 NSS_EXTERN NSSGeneralName *
01891 NSSGeneralName_Create
01892 (
01893   NSSGeneralNameChoice choice,
01894   void *arg
01895 );
01896 
01897 /*
01898  * NSSGeneralName_Destroy
01899  * 
01900  * This routine will destroy a General Name object.  It should 
01901  * eventually be called on all General Names created without an arena.
01902  * While it is not necessary to call it on General Names created within
01903  * an arena, it is not an error to do so.  This routine returns a
01904  * PRStatus value; if successful, it will return PR_SUCCESS. If 
01905  * usuccessful, it will create an error stack and return PR_FAILURE.
01906  *
01907  * The error may be one of the following values:
01908  *  NSS_ERROR_INVALID_GENERAL_NAME
01909  *
01910  * Return value:
01911  *  PR_FAILURE upon failure
01912  *  PR_SUCCESS upon success
01913  */
01914 
01915 NSS_EXTERN PRStatus
01916 NSSGeneralName_Destroy
01917 (
01918   NSSGeneralName *generalName
01919 );
01920 
01921 /*
01922  * NSSGeneralName_GetDEREncoding
01923  *
01924  * This routine will DER-encode a name object.  If the optional arena
01925  * argument is non-null, the memory used will be obtained from that
01926  * arena; otherwise, the memory will be obtained from the heap.  This
01927  * routine may return null upon error, in which case it will have 
01928  * created an error stack.
01929  *
01930  * The error may be one of the following values:
01931  *  NSS_ERROR_INVALID_GENERAL_NAME
01932  *  NSS_ERROR_NO_MEMORY
01933  *
01934  * Return value:
01935  *  NULL upon error
01936  *  The DER encoding of this NSSGeneralName
01937  */
01938 
01939 NSS_EXTERN NSSDER *
01940 NSSGeneralName_GetDEREncoding
01941 (
01942   NSSGeneralName *generalName,
01943   NSSArena *arenaOpt
01944 );
01945 
01946 /*
01947  * NSSGeneralName_GetUTF8Encoding
01948  *
01949  * This routine returns a UTF8 string containing a string 
01950  * representation of the General Name in the format specified by the
01951  * underlying name choice.  If the optional arena argument is 
01952  * non-null, the memory used will be obtained from that arena; 
01953  * otherwise, the memory will be obtained from the heap.  This routine
01954  * may return NULL upon error, in which case it will have created an
01955  * error stack.
01956  *
01957  * The error may be one of the following values:
01958  *  NSS_ERROR_INVALID_GENERAL_NAME
01959  *  NSS_ERROR_NO_MEMORY
01960  *
01961  * Return value:
01962  *  NULL upon error
01963  *  A pointer to a UTF8 string
01964  */
01965 
01966 NSS_EXTERN NSSUTF8 *
01967 NSSGeneralName_GetUTF8Encoding
01968 (
01969   NSSGeneralName *generalName,
01970   NSSArena *arenaOpt
01971 );
01972 
01973 /*
01974  * NSSGeneralName_GetChoice
01975  *
01976  * This routine returns the type of choice underlying the specified 
01977  * general name.  The return value will be a member of the 
01978  * NSSGeneralNameChoice enumeration.  This routine may return 
01979  * NSSGeneralNameChoiceInvalid upon error, in which case it will have 
01980  * created an error stack.
01981  *
01982  * The error may be one of the following values:
01983  *  NSS_ERROR_INVALID_GENERAL_NAME
01984  *
01985  * Return value:
01986  *  NSSGeneralNameChoiceInvalid upon error
01987  *  An other member of the NSSGeneralNameChoice enumeration 
01988  */
01989 
01990 NSS_EXTERN NSSGeneralNameChoice
01991 NSSGeneralName_GetChoice
01992 (
01993   NSSGeneralName *generalName
01994 );
01995 
01996 /*
01997  * NSSGeneralName_GetOtherName
01998  *
01999  * If the choice underlying the specified NSSGeneralName is that of an
02000  * Other Name, this routine will return a pointer to that Other name.
02001  * Otherwise, this routine will place an error on the error stack, and
02002  * return NULL.  If the optional arena argument is non-null, the memory
02003  * required will be obtained from that arena; otherwise, the memory 
02004  * will be obtained from the heap.  The caller owns the returned 
02005  * pointer.  This routine may return NULL upon error, in which case it
02006  * will have created an error stack.
02007  *
02008  * The error may be one of the following values:
02009  *  NSS_ERROR_INVALID_GENERAL_NAME
02010  *  NSS_ERROR_WRONG_CHOICE
02011  *  NSS_ERROR_NO_MEMORY
02012  *
02013  * Return value:
02014  *  NULL upon error
02015  *  A caller-owned pointer to an NSSOtherName
02016  */
02017 
02018 NSS_EXTERN NSSOtherName *
02019 NSSGeneralName_GetOtherName
02020 (
02021   NSSGeneralName *generalName,
02022   NSSArena *arenaOpt
02023 );
02024 
02025 /*
02026  * NSSGeneralName_GetRfc822Name
02027  *
02028  * If the choice underlying the specified NSSGeneralName is that of an
02029  * RFC 822 Name, this routine will return a pointer to that name.
02030  * Otherwise, this routine will place an error on the error stack, and
02031  * return NULL.  If the optional arena argument is non-null, the memory
02032  * required will be obtained from that arena; otherwise, the memory 
02033  * will be obtained from the heap.  The caller owns the returned 
02034  * pointer.  This routine may return NULL upon error, in which case it
02035  * will have created an error stack.
02036  *
02037  * The error may be one of the following values:
02038  *  NSS_ERROR_INVALID_GENERAL_NAME
02039  *  NSS_ERROR_WRONG_CHOICE
02040  *  NSS_ERROR_NO_MEMORY
02041  *
02042  * Return value:
02043  *  NULL upon error
02044  *  A caller-owned pointer to an NSSRFC822Name
02045  */
02046 
02047 NSS_EXTERN NSSRFC822Name *
02048 NSSGeneralName_GetRfc822Name
02049 (
02050   NSSGeneralName *generalName,
02051   NSSArena *arenaOpt
02052 );
02053 
02054 /*
02055  * NSSGeneralName_GetDNSName
02056  *
02057  * If the choice underlying the specified NSSGeneralName is that of a 
02058  * DNS Name, this routine will return a pointer to that DNS name.
02059  * Otherwise, this routine will place an error on the error stack, and
02060  * return NULL.  If the optional arena argument is non-null, the memory
02061  * required will be obtained from that arena; otherwise, the memory 
02062  * will be obtained from the heap.  The caller owns the returned 
02063  * pointer.  This routine may return NULL upon error, in which case it
02064  * will have created an error stack.
02065  *
02066  * The error may be one of the following values:
02067  *  NSS_ERROR_INVALID_GENERAL_NAME
02068  *  NSS_ERROR_WRONG_CHOICE
02069  *  NSS_ERROR_NO_MEMORY
02070  *
02071  * Return value:
02072  *  NULL upon error
02073  *  A caller-owned pointer to an NSSDNSName
02074  */
02075 
02076 NSS_EXTERN NSSDNSName *
02077 NSSGeneralName_GetDNSName
02078 (
02079   NSSGeneralName *generalName,
02080   NSSArena *arenaOpt
02081 );
02082 
02083 /*
02084  * NSSGeneralName_GetX400Address
02085  *
02086  * If the choice underlying the specified NSSGeneralName is that of an
02087  * X.400 Address, this routine will return a pointer to that Address.
02088  * Otherwise, this routine will place an error on the error stack, and
02089  * return NULL.  If the optional arena argument is non-null, the memory
02090  * required will be obtained from that arena; otherwise, the memory 
02091  * will be obtained from the heap.  The caller owns the returned 
02092  * pointer.  This routine may return NULL upon error, in which case it
02093  * will have created an error stack.
02094  *
02095  * The error may be one of the following values:
02096  *  NSS_ERROR_INVALID_GENERAL_NAME
02097  *  NSS_ERROR_WRONG_CHOICE
02098  *  NSS_ERROR_NO_MEMORY
02099  *
02100  * Return value:
02101  *  NULL upon error
02102  *  A caller-owned pointer to an NSSX400Address
02103  */
02104 
02105 NSS_EXTERN NSSX400Address *
02106 NSSGeneralName_GetX400Address
02107 (
02108   NSSGeneralName *generalName,
02109   NSSArena *arenaOpt
02110 );
02111 
02112 /*
02113  * NSSGeneralName_GetDirectoryName
02114  *
02115  * If the choice underlying the specified NSSGeneralName is that of a
02116  * (directory) Name, this routine will return a pointer to that name.
02117  * Otherwise, this routine will place an error on the error stack, and
02118  * return NULL.  If the optional arena argument is non-null, the memory
02119  * required will be obtained from that arena; otherwise, the memory 
02120  * will be obtained from the heap.  The caller owns the returned 
02121  * pointer.  This routine may return NULL upon error, in which case it
02122  * will have created an error stack.
02123  *
02124  * The error may be one of the following values:
02125  *  NSS_ERROR_INVALID_GENERAL_NAME
02126  *  NSS_ERROR_WRONG_CHOICE
02127  *  NSS_ERROR_NO_MEMORY
02128  *
02129  * Return value:
02130  *  NULL upon error
02131  *  A caller-owned pointer to an NSSName
02132  */
02133 
02134 NSS_EXTERN NSSName *
02135 NSSGeneralName_GetName
02136 (
02137   NSSGeneralName *generalName,
02138   NSSArena *arenaOpt
02139 );
02140 
02141 /*
02142  * NSSGeneralName_GetEdiPartyName
02143  *
02144  * If the choice underlying the specified NSSGeneralName is that of an
02145  * EDI Party Name, this routine will return a pointer to that name.
02146  * Otherwise, this routine will place an error on the error stack, and
02147  * return NULL.  If the optional arena argument is non-null, the memory
02148  * required will be obtained from that arena; otherwise, the memory 
02149  * will be obtained from the heap.  The caller owns the returned 
02150  * pointer.  This routine may return NULL upon error, in which case it
02151  * will have created an error stack.
02152  *
02153  * The error may be one of the following values:
02154  *  NSS_ERROR_INVALID_GENERAL_NAME
02155  *  NSS_ERROR_WRONG_CHOICE
02156  *  NSS_ERROR_NO_MEMORY
02157  *
02158  * Return value:
02159  *  NULL upon error
02160  *  A caller-owned pointer to an NSSEdiPartyName
02161  */
02162 
02163 NSS_EXTERN NSSEdiPartyName *
02164 NSSGeneralName_GetEdiPartyName
02165 (
02166   NSSGeneralName *generalName,
02167   NSSArena *arenaOpt
02168 );
02169 
02170 /*
02171  * NSSGeneralName_GetUniformResourceIdentifier
02172  *
02173  * If the choice underlying the specified NSSGeneralName is that of a
02174  * URI, this routine will return a pointer to that URI.
02175  * Otherwise, this routine will place an error on the error stack, and
02176  * return NULL.  If the optional arena argument is non-null, the memory
02177  * required will be obtained from that arena; otherwise, the memory 
02178  * will be obtained from the heap.  The caller owns the returned 
02179  * pointer.  This routine may return NULL upon error, in which case it
02180  * will have created an error stack.
02181  *
02182  * The error may be one of the following values:
02183  *  NSS_ERROR_INVALID_GENERAL_NAME
02184  *  NSS_ERROR_WRONG_CHOICE
02185  *  NSS_ERROR_NO_MEMORY
02186  *
02187  * Return value:
02188  *  NULL upon error
02189  *  A caller-owned pointer to an NSSURI
02190  */
02191 
02192 NSS_EXTERN NSSURI *
02193 NSSGeneralName_GetUniformResourceIdentifier
02194 (
02195   NSSGeneralName *generalName,
02196   NSSArena *arenaOpt
02197 );
02198 
02199 /*
02200  * NSSGeneralName_GetIPAddress
02201  *
02202  * If the choice underlying the specified NSSGeneralName is that of an
02203  * IP Address , this routine will return a pointer to that address.
02204  * Otherwise, this routine will place an error on the error stack, and
02205  * return NULL.  If the optional arena argument is non-null, the memory
02206  * required will be obtained from that arena; otherwise, the memory 
02207  * will be obtained from the heap.  The caller owns the returned 
02208  * pointer.  This routine may return NULL upon error, in which case it
02209  * will have created an error stack.
02210  *
02211  * The error may be one of the following values:
02212  *  NSS_ERROR_INVALID_GENERAL_NAME
02213  *  NSS_ERROR_WRONG_CHOICE
02214  *  NSS_ERROR_NO_MEMORY
02215  *
02216  * Return value:
02217  *  NULL upon error
02218  *  A caller-owned pointer to an NSSIPAddress
02219  */
02220 
02221 NSS_EXTERN NSSIPAddress *
02222 NSSGeneralName_GetIPAddress
02223 (
02224   NSSGeneralName *generalName,
02225   NSSArena *arenaOpt
02226 );
02227 
02228 /*
02229  * NSSGeneralName_GetRegisteredID
02230  *
02231  * If the choice underlying the specified NSSGeneralName is that of a
02232  * Registered ID, this routine will return a pointer to that ID.
02233  * Otherwise, this routine will place an error on the error stack, and
02234  * return NULL.  If the optional arena argument is non-null, the memory
02235  * required will be obtained from that arena; otherwise, the memory 
02236  * will be obtained from the heap.  The caller owns the returned 
02237  * pointer.  This routine may return NULL upon error, in which case it
02238  * will have created an error stack.
02239  *
02240  * The error may be one of the following values:
02241  *  NSS_ERROR_INVALID_GENERAL_NAME
02242  *  NSS_ERROR_WRONG_CHOICE
02243  *  NSS_ERROR_NO_MEMORY
02244  *
02245  * Return value:
02246  *  NULL upon error
02247  *  A caller-owned pointer to an NSSRegisteredID
02248  */
02249 
02250 NSS_EXTERN NSSRegisteredID *
02251 NSSGeneralName_GetRegisteredID
02252 (
02253   NSSGeneralName *generalName,
02254   NSSArena *arenaOpt
02255 );
02256 
02257 /*
02258  * NSSGeneralName_GetSpecifiedChoice
02259  *
02260  * If the choice underlying the specified NSSGeneralName matches the
02261  * specified choice, a caller-owned pointer to that underlying object
02262  * will be returned.  Otherwise, an error will be placed on the error
02263  * stack and NULL will be returned.  If the optional arena argument
02264  * is non-null, the memory required will be obtained from that arena;
02265  * otherwise, the memory will be obtained from the heap.  The caller
02266  * owns the returned pointer.  This routine may return NULL upon 
02267  * error, in which caes it will have created an error stack.
02268  *
02269  * The error may be one of the following values:
02270  *  NSS_ERROR_INVALID_GENERAL_NAME
02271  *  NSS_ERROR_WRONG_CHOICE
02272  *  NSS_ERROR_NO_MEMORY
02273  *
02274  * Return value:
02275  *  NULL upon error
02276  *  A caller-owned pointer, which must be typecast
02277  */
02278 
02279 NSS_EXTERN void *
02280 NSSGeneralName_GetSpecifiedChoice
02281 (
02282   NSSGeneralName *generalName,
02283   NSSGeneralNameChoice choice,
02284   NSSArena *arenaOpt
02285 );
02286 
02287 /*
02288  * NSSGeneralName_Compare
02289  * 
02290  * This routine compares two General Names for equality.  For two 
02291  * General Names to be equal, they must have the same choice of
02292  * underlying types, and the underlying values must be equal.  The
02293  * result of the comparison will be stored at the location pointed
02294  * to by the "equalp" variable, which must point to a valid PRBool.
02295  * This routine may return PR_FAILURE upon error, in which case it
02296  * will have created an error stack.
02297  *
02298  * The error may be one of the following value:
02299  *  NSS_ERROR_INVALID_GENERAL_NAME
02300  *  NSS_ERROR_INVALID_ARGUMENT
02301  *
02302  * Return value:
02303  *  PR_FAILURE upon error
02304  *  PR_SUCCESS upon a successful comparison (equal or not)
02305  */
02306 
02307 NSS_EXTERN PRStatus
02308 NSSGeneralName_Compare
02309 (
02310   NSSGeneralName *generalName1,
02311   NSSGeneralName *generalName2,
02312   PRBool *equalp
02313 );
02314 
02315 /*
02316  * NSSGeneralName_Duplicate
02317  *
02318  * This routine duplicates the specified General Name.  If the optional
02319  * arena argument is non-null, the memory required will be obtained
02320  * from that arena; otherwise, the memory will be obtained from the
02321  * heap.  This routine may return NULL upon error, in which case it 
02322  * will have created an error stack.
02323  *
02324  * The error may be one of the following values:
02325  *  NSS_ERROR_INVALID_GENERAL_NAME
02326  *  NSS_ERROR_NO_MEMORY
02327  *
02328  * Return value:
02329  *  NULL upon error
02330  *  A pointer to a new NSSGeneralName
02331  */
02332 
02333 NSS_EXTERN NSSGeneralName *
02334 NSSGeneralName_Duplicate
02335 (
02336   NSSGeneralName *generalName,
02337   NSSArena *arenaOpt
02338 );
02339 
02340 /*
02341  * NSSGeneralName_GetUID
02342  *
02343  * This routine will attempt to derive a user identifier from the
02344  * specified general name, if the choices and content of the name
02345  * permit.  If the General Name is a (directory) Name consisting
02346  * of a Sequence of Relative Distinguished Names containing a UID
02347  * attribute, the UID will be the value of that attribute.  Note
02348  * that no UID attribute is defined in either PKIX or PKCS#9; 
02349  * rather, this seems to derive from RFC 1274, which defines the
02350  * type as a caseIgnoreString.  We'll return a Directory String.
02351  * If the optional arena argument is non-null, the memory used
02352  * will be obtained from that arena; otherwise, the memory will be
02353  * obtained from the heap.  This routine may return NULL upon error,
02354  * in which case it will have created an error stack.
02355  *
02356  * The error may be one of the following values:
02357  *  NSS_ERROR_INVALID_GENERAL_NAME
02358  *  NSS_ERROR_NO_UID
02359  *  NSS_ERROR_NO_MEMORY
02360  *
02361  * Return value:
02362  *  NULL upon error
02363  *  A pointer to a UTF8 String.
02364  */
02365 
02366 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02367 NSSGeneralName_GetUID
02368 (
02369   NSSGeneralName *generalName,
02370   NSSArena *arenaOpt
02371 );
02372 
02373 /*
02374  * NSSGeneralName_GetEmail
02375  *
02376  * This routine will attempt to derive an email address from the
02377  * specified general name, if the choices and content of the name
02378  * permit.  If the General Name is a (directory) Name consisting
02379  * of a Sequence of Relative Distinguished names containing either
02380  * a PKIX email address or a PKCS#9 email address, the result will
02381  * be the value of that attribute.  If the General Name is an RFC 822
02382  * Name, the result will be the string form of that name.  If the
02383  * optional arena argument is non-null, the memory used will be 
02384  * obtained from that arena; otherwise, the memory will be obtained
02385  * from the heap.  This routine may return NULL upon error, in which
02386  * case it will have created an error stack.
02387  *
02388  * The error may be one of the following values:
02389  *  NSS_ERROR_INVALID_GENERAL_NAME
02390  *  NSS_ERROR_NO_EMAIL
02391  *  NSS_ERROR_NO_MEMORY
02392  *
02393  * Return value:
02394  *  NULL upon error
02395  *  A pointer to a UTF8 String
02396  */
02397 
02398 NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5String */
02399 NSSGeneralName_GetEmail
02400 (
02401   NSSGeneralName *generalName,
02402   NSSArena *arenaOpt
02403 );
02404 
02405 /*
02406  * NSSGeneralName_GetCommonName
02407  *
02408  * This routine will attempt to derive a common name from the
02409  * specified general name, if the choices and content of the name
02410  * permit.  If the General Name is a (directory) Name consisting
02411  * of a Sequence of Relative Distinguished names containing a PKIX
02412  * Common Name, the result will be that name.  If the optional arena 
02413  * argument is non-null, the memory used will be obtained from that 
02414  * arena; otherwise, the memory will be obtained from the heap.  This 
02415  * routine may return NULL upon error, in which case it will have 
02416  * created an error stack.
02417  *
02418  * The error may be one of the following values:
02419  *  NSS_ERROR_INVALID_GENERAL_NAME
02420  *  NSS_ERROR_NO_COMMON_NAME
02421  *  NSS_ERROR_NO_MEMORY
02422  *
02423  * Return value:
02424  *  NULL upon error
02425  *  A pointer to a UTF8 String
02426  */
02427 
02428 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02429 NSSGeneralName_GetCommonName
02430 (
02431   NSSGeneralName *generalName,
02432   NSSArena *arenaOpt
02433 );
02434 
02435 /*
02436  * NSSGeneralName_GetOrganization
02437  *
02438  * This routine will attempt to derive an organisation name from the
02439  * specified general name, if the choices and content of the name
02440  * permit.  If the General Name is a (directory) Name consisting
02441  * of a Sequence of Relative Distinguished names containing an
02442  * Organization, the result will be the value of that attribute.  
02443  * If the optional arena argument is non-null, the memory used will 
02444  * be obtained from that arena; otherwise, the memory will be obtained
02445  * from the heap.  This routine may return NULL upon error, in which 
02446  * case it will have created an error stack.
02447  *
02448  * The error may be one of the following values:
02449  *  NSS_ERROR_INVALID_GENERAL_NAME
02450  *  NSS_ERROR_NO_ORGANIZATION
02451  *  NSS_ERROR_NO_MEMORY
02452  *
02453  * Return value:
02454  *  NULL upon error
02455  *  A pointer to a UTF8 String
02456  */
02457 
02458 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02459 NSSGeneralName_GetOrganization
02460 (
02461   NSSGeneralName *generalName,
02462   NSSArena *arenaOpt
02463 );
02464 
02465 /*
02466  * NSSGeneralName_GetOrganizationalUnits
02467  *
02468  * This routine will attempt to derive a sequence of organisational 
02469  * unit names from the specified general name, if the choices and 
02470  * content of the name permit.  If the General Name is a (directory) 
02471  * Name consisting of a Sequence of Relative Distinguished names 
02472  * containing one or more organisational units, the result will 
02473  * consist of those units.  If the optional arena  argument is non-
02474  * null, the memory used will be obtained from that arena; otherwise, 
02475  * the memory will be obtained from the heap.  This routine may return 
02476  * NULL upon error, in which case it will have created an error stack.
02477  *
02478  * The error may be one of the following values:
02479  *  NSS_ERROR_INVALID_GENERAL_NAME
02480  *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
02481  *  NSS_ERROR_NO_MEMORY
02482  *
02483  * Return value:
02484  *  NULL upon error
02485  *  A pointer to a null-terminated array of UTF8 Strings
02486  */
02487 
02488 NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
02489 NSSGeneralName_GetOrganizationalUnits
02490 (
02491   NSSGeneralName *generalName,
02492   NSSArena *arenaOpt
02493 );
02494 
02495 /*
02496  * NSSGeneralName_GetStateOrProvince
02497  *
02498  * This routine will attempt to derive a state or province name from 
02499  * the specified general name, if the choices and content of the name
02500  * permit.  If the General Name is a (directory) Name consisting
02501  * of a Sequence of Relative Distinguished names containing a state or 
02502  * province, the result will be the value of that attribute.  If the 
02503  * optional arena argument is non-null, the memory used will be 
02504  * obtained from that arena; otherwise, the memory will be obtained 
02505  * from the heap.  This routine may return NULL upon error, in which 
02506  * case it will have created an error stack.
02507  *
02508  * The error may be one of the following values:
02509  *  NSS_ERROR_INVALID_GENERAL_NAME
02510  *  NSS_ERROR_NO_STATE_OR_PROVINCE
02511  *  NSS_ERROR_NO_MEMORY
02512  *
02513  * Return value:
02514  *  NULL upon error
02515  *  A pointer to a UTF8 String
02516  */
02517 
02518 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02519 NSSGeneralName_GetStateOrProvince
02520 (
02521   NSSGeneralName *generalName,
02522   NSSArena *arenaOpt
02523 );
02524 
02525 /*
02526  * NSSGeneralName_GetLocality
02527  *
02528  * This routine will attempt to derive a locality name from 
02529  * the specified general name, if the choices and content of the name
02530  * permit.  If the General Name is a (directory) Name consisting
02531  * of a Sequence of Relative Distinguished names containing a Locality, 
02532  * the result will be the value of that attribute.  If the optional 
02533  * arena argument is non-null, the memory used will be obtained from 
02534  * that arena; otherwise, the memory will be obtained from the heap.  
02535  * This routine may return NULL upon error, in which case it will have 
02536  * created an error stack.
02537  *
02538  * The error may be one of the following values:
02539  *  NSS_ERROR_INVALID_GENERAL_NAME
02540  *  NSS_ERROR_NO_LOCALITY
02541  *  NSS_ERROR_NO_MEMORY
02542  *
02543  * Return value:
02544  *  NULL upon error
02545  *  A pointer to a UTF8 String
02546  */
02547 
02548 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02549 NSSGeneralName_GetLocality
02550 (
02551   NSSGeneralName *generalName,
02552   NSSArena *arenaOpt
02553 );
02554 
02555 /*
02556  * NSSGeneralName_GetCountry
02557  *
02558  * This routine will attempt to derive a country name from the 
02559  * specified general name, if the choices and content of the name 
02560  * permit.  If the General Name is a (directory) Name consisting of a
02561  * Sequence of Relative Distinguished names containing a Country, the 
02562  * result will be the value of that attribute.  If the optional 
02563  * arena argument is non-null, the memory used will be obtained from 
02564  * that arena; otherwise, the memory will be obtained from the heap.  
02565  * This routine may return NULL upon error, in which case it will have 
02566  * created an error stack.
02567  *
02568  * The error may be one of the following values:
02569  *  NSS_ERROR_INVALID_GENERAL_NAME
02570  *  NSS_ERROR_NO_COUNTRY
02571  *  NSS_ERROR_NO_MEMORY
02572  *
02573  * Return value:
02574  *  NULL upon error
02575  *  A pointer to a UTF8 String
02576  */
02577 
02578 NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
02579 NSSGeneralName_GetCountry
02580 (
02581   NSSGeneralName *generalName,
02582   NSSArena *arenaOpt
02583 );
02584 
02585 /*
02586  * NSSGeneralName_GetAttribute
02587  *
02588  * If the specified general name is a (directory) name consisting
02589  * of a Sequence of Relative Distinguished Names containing an 
02590  * attribute with the specified type, and the actual value of that
02591  * attribute may be expressed with a Directory String, then the
02592  * value of that attribute will be returned as a Directory String.
02593  * If the optional arena argument is non-null, the memory used will
02594  * be obtained from that arena; otherwise, the memory will be obtained
02595  * from the heap.  This routine may return NULL upon error, in which
02596  * case it will have created an error stack.
02597  *
02598  * The error may be one of the following values:
02599  *  NSS_ERROR_INVALID_GENERAL_NAME
02600  *  NSS_ERROR_NO_ATTRIBUTE
02601  *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
02602  *
02603  * Return value:
02604  *  NULL upon error
02605  *  A pointer to a UTF8 String
02606  */
02607 
02608 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02609 NSSGeneralName_GetAttribute
02610 (
02611   NSSGeneralName *generalName,
02612   NSSOID *attribute,
02613   NSSArena *arenaOpt
02614 );
02615 
02616 /*
02617  * NSSGeneralNameSeq
02618  *
02619  * The public "methods" regarding this "object" are:
02620  *
02621  *  NSSGeneralNameSeq_CreateFromBER   -- constructor
02622  *  NSSGeneralNameSeq_Create          -- constructor
02623  *
02624  *  NSSGeneralNameSeq_Destroy
02625  *  NSSGeneralNameSeq_GetDEREncoding
02626  *  NSSGeneralNameSeq_AppendGeneralName
02627  *  NSSGeneralNameSeq_GetGeneralNameCount
02628  *  NSSGeneralNameSeq_GetGeneralName
02629  *  NSSGeneralNameSeq_Compare
02630  *  NSSGeneralnameSeq_Duplicate
02631  */
02632 
02633 /*
02634  * NSSGeneralNameSeq_CreateFromBER
02635  *
02636  * This routine creates a general name sequence by decoding a BER-
02637  * or DER-encoded GeneralNames.  If the optional arena argument is
02638  * non-null, the memory used will be obtained from that arena; 
02639  * otherwise, the memory will be obtained from the heap.  This routine
02640  * may return NULL upon error, in which case it will have created an
02641  * error stack.
02642  *
02643  * The error may be one of the following values:
02644  *  NSS_ERROR_INVALID_BER
02645  *  NSS_ERROR_NO_MEMORY
02646  *
02647  * Return value:
02648  *  NULL upon error
02649  *  A pointer to an NSSGeneralNameSeq upon success
02650  */
02651 
02652 NSS_EXTERN NSSGeneralNameSeq *
02653 NSSGeneralNameSeq_CreateFromBER
02654 (
02655   NSSArena *arenaOpt,
02656   NSSBER *berGeneralNameSeq
02657 );
02658 
02659 /*
02660  * NSSGeneralNameSeq_Create
02661  *
02662  * This routine creates an NSSGeneralNameSeq from one or more General
02663  * Names.  The final argument to this routine must be NULL.  If the
02664  * optional arena argument is non-null, the memory used will be 
02665  * obtained from that arena; otherwise, the memory will be obtained 
02666  * from the heap.  This routine may return NULL upon error, in which
02667  * case it will have created an error stack.
02668  *
02669  * The error may be one of the following values:
02670  *  NSS_ERROR_NO_MEMORY
02671  *  NSS_ERROR_INVALID_GENERAL_NAME
02672  *
02673  * Return value:
02674  *  NULL upon error
02675  *  A pointer to an NSSGeneralNameSeq upon success
02676  */
02677 
02678 NSS_EXTERN NSSGeneralNameSeq *
02679 NSSGeneralNameSeq_Create
02680 (
02681   NSSArena *arenaOpt,
02682   NSSGeneralName *generalName1,
02683   ...
02684 );
02685 
02686 /*
02687  * NSSGeneralNameSeq_Destroy
02688  *
02689  * This routine will destroy an NSSGeneralNameSeq object.  It should
02690  * eventually be called on all NSSGeneralNameSeqs created without an
02691  * arena.  While it is not necessary to call it on NSSGeneralNameSeq's
02692  * created within an arena, it is not an error to do so.  This routine
02693  * returns a PRStatus value; if successful, it will return PR_SUCCESS.
02694  * If unsuccessful, it will create an error stack and return PR_FAILURE.
02695  *
02696  * The error may be one of the following values:
02697  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02698  *
02699  * Return value:
02700  *  PR_FAILURE upon error
02701  *  PR_SUCCESS upon success
02702  */
02703 
02704 NSS_EXTERN PRStatus
02705 NSSGeneralNameSeq_Destroy
02706 (
02707   NSSGeneralNameSeq *generalNameSeq
02708 );
02709 
02710 /*
02711  * NSSGeneralNameSeq_GetDEREncoding
02712  *
02713  * This routine will DER-encode an NSSGeneralNameSeq object.  If the
02714  * optional arena argument is non-null, the memory used will be 
02715  * obtained from that arena; otherwise, the memory will be obtained
02716  * from the heap.  This routine may return null upon error, in which
02717  * case it will have created an error stack.
02718  *
02719  * The error may be one of the following values:
02720  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02721  *  NSS_ERROR_NO_MEMORY
02722  *
02723  * Return value:
02724  *  NULL upon error
02725  *  The DER encoding of this NSSGeneralNameSeq
02726  */
02727 
02728 NSS_EXTERN NSSDER *
02729 NSSGeneralNameSeq_GetDEREncoding
02730 (
02731   NSSGeneralNameSeq *generalNameSeq,
02732   NSSArena *arenaOpt
02733 );
02734 
02735 /*
02736  * NSSGeneralNameSeq_AppendGeneralName
02737  *
02738  * This routine appends a General Name to the end of the existing
02739  * General Name Sequence.  If the sequence was created with a non-null
02740  * arena argument, that same arena will be used for any additional
02741  * required memory.  If the sequence was created with a NULL arena
02742  * argument, any additional memory will be obtained from the heap.
02743  * This routine returns a PRStatus value; it will return PR_SUCCESS
02744  * upon success, and upon failure it will create an error stack and 
02745  * return PR_FAILURE.
02746  *
02747  * The error may be one of the following values:
02748  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02749  *  NSS_ERROR_INVALID_GENERAL_NAME
02750  *  NSS_ERROR_NO_MEMORY
02751  * 
02752  * Return value:
02753  *  PR_SUCCESS upon success
02754  *  PR_FAILURE upon failure.
02755  */
02756 
02757 NSS_EXTERN PRStatus
02758 NSSGeneralNameSeq_AppendGeneralName
02759 (
02760   NSSGeneralNameSeq *generalNameSeq,
02761   NSSGeneralName *generalName
02762 );
02763 
02764 /*
02765  * NSSGeneralNameSeq_GetGeneralNameCount
02766  *
02767  * This routine returns the cardinality of the specified General name
02768  * Sequence.  This routine may return 0 upon error, in which case it
02769  * will have created an error stack.
02770  *
02771  * The error may be one of the following values:
02772  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02773  *
02774  * Return value;
02775  *  0 upon error
02776  *  A positive number upon success
02777  */
02778 
02779 NSS_EXTERN PRUint32
02780 NSSGeneralNameSeq_GetGeneralNameCount
02781 (
02782   NSSGeneralNameSeq *generalNameSeq
02783 );
02784 
02785 /*
02786  * NSSGeneralNameSeq_GetGeneralName
02787  *
02788  * This routine returns a pointer to the i'th General Name in the 
02789  * specified General Name Sequence.  The value of the variable 'i' is
02790  * on the range [0,c) where c is the cardinality returned from 
02791  * NSSGeneralNameSeq_GetGeneralNameCount.  The caller owns the General
02792  * Name the pointer to which is returned.  If the optional arena
02793  * argument is non-null, the memory used will be obtained from that
02794  * arena; otherwise, the memory will be obtained from the heap.  This
02795  * routine may return NULL upon error, in which case it will have 
02796  * created an error stack.
02797  *
02798  * The error may be one of the following values:
02799  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02800  *  NSS_ERROR_VALUE_OUT_OF_RANGE
02801  *  NSS_ERROR_NO_MEMORY
02802  *
02803  * Return value:
02804  *  NULL upon error
02805  *  A caller-owned pointer to a General Name.
02806  */
02807 
02808 NSS_EXTERN NSSGeneralName *
02809 NSSGeneralNameSeq_GetGeneralName
02810 (
02811   NSSGeneralNameSeq *generalNameSeq,
02812   NSSArena *arenaOpt,
02813   PRUint32 i
02814 );
02815 
02816 /*
02817  * NSSGeneralNameSeq_Compare
02818  *
02819  * This routine compares two General Name Sequences for equality.  For
02820  * two General Name Sequences to be equal, they must have the same
02821  * cardinality, and each General Name in one sequence must be equal to
02822  * the corresponding General Name in the other.  The result of the
02823  * comparison will be stored at the location pointed to by the "equalp"
02824  * variable, which must point to a valid PRBool.  This routine may 
02825  * return PR_FAILURE upon error, in which case it will have created an
02826  * error stack.
02827  *
02828  * The error may be one of the following values:
02829  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02830  *  NSS_ERROR_INVALID_ARGUMENT
02831  *
02832  * Return value:
02833  *  PR_FAILURE upon error
02834  *  PR_SUCCESS upon a successful comparison (equal or not)
02835  */
02836 
02837 NSS_EXTERN PRStatus
02838 NSSGeneralNameSeq_Compare
02839 (
02840   NSSGeneralNameSeq *generalNameSeq1,
02841   NSSGeneralNameSeq *generalNameSeq2,
02842   PRBool *equalp
02843 );
02844 
02845 /*
02846  * NSSGeneralNameSeq_Duplicate
02847  *
02848  * This routine duplicates the specified sequence of general names.  If
02849  * the optional arena argument is non-null, the memory required will be
02850  * obtained from that arena; otherwise, the memory will be obtained 
02851  * from the heap.  This routine may return NULL upon error, in which 
02852  * case it will have created an error stack.
02853  *
02854  * The error may be one of the following values:
02855  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02856  *  NSS_ERROR_NO_MEMORY
02857  *
02858  * Return value:
02859  *  NULL upon error
02860  *  A pointer to a new General Name Sequence.
02861  */
02862 
02863 NSS_EXTERN NSSGeneralNameSeq *
02864 NSSGeneralNameSeq_Duplicate
02865 (
02866   NSSGeneralNameSeq *generalNameSeq,
02867   NSSArena *arenaOpt
02868 );
02869 
02870 PR_END_EXTERN_C
02871 
02872 #endif /* NSSPT1M_H */