.\" $Header: filename revision date author state$
.TH citr\_cvt 3
.ds )H Centre for Information Technology Research
.ds ]W CiTR April 93
.SH NAME
CiTRCvtIpChar, CiTRCvtE164Char, CiTRCvtE164CharAMS, CiTRCvtPhysChar, CiTRCvtMACChar, CiTRCvtCPIpChar,
CiTRCvtCharIp, CiTRCvtCharE164, CiTRCvtCharPhys, CiTRCvtCharMAC, CiTRCvtCharCPIp
\- Data type translation routines
.SH SYNOPSIS
.B #include <citr_cvt.h>
.PP
.B Boole   CiTRCvtIpChar(const OVcIpAddress in, char *out)
.PP
.B Boole   CiTRCvtE164Char(const CiTRString *in, char *out)
.PP
.B Boole   CiTRCvtE164CharAMS(const CiTRString *in, char *out)
.PP
.B Boole   CiTRCvtPhysChar(const CiTRString *in, char *out)
.PP
.B Boole   CiTRCvtMACChar(const CiTRString *in, char *out)
.PP
.B Boole   CiTRCvtCPIpChar(const CiTRString *in, char *out)
.PP
.B Boole   CiTRCvtCharIp(const char *in, OVcIpAddress out)
.PP
.B Boole   CiTRCvtCharE164(const char *in, CiTRString *out)
.PP
.B Boole   CiTRCvtCharPhys(const char *in, CiTRString *out)
.PP
.B Boole   CiTRCvtCharMAC(const char *in, CiTRString *out)
.PP
.B Boole   CiTRCvtCharCPIp(const char *in, CiTRString *out)
.PP
.SH DESCRIPTION
Conversion routines between various datatypes used in FMS for
representing CP datatypes and strings for display.

.PP
.DS
   The caller allocates the char buffer for the conversion to
   char routines, and the structure for the others. Within the struct
   they have allocated the buffer pointed to by value. The functions
   return TRUE on success.

 The format of these E.164, MAC and IP addresses are described below
 (Based on mail from Andrew Mudge, and FAX from CP)

E164    "XX 999 999 99 999 9999"  where 9 is any numeric digit. I will 
                                check if there are any padding issues 
                                we need to be concerned about. 

802.3   "99 99 99 99 99 99"     where 9 is any numeric digit. 
                                No padding issues here. 
                                eg : 43 71 86 08 55 00

IP      "999.999.999.999"       Standard dotted notation. 
                                eg : 144.136.9.8

XX code        meaning

NA 0x4        16 bit

EA 0x8        48 bit

IU 0xc        Individual 60 bit publically administered

IR 0xd        Individual 60 bit privately administered

GU 0xe        Group 60 bit publically administered

GR 0xf        Group 60 bit privately administered

A quick note on E.164 address padding. Should an address be less than the
required 64 bits the trailing nibbles are padded hex 'f'.  The padding
will only occur on the trailing side of the address.

In the case where an E.164 address is to be displayed that is less than 
maximum length please pad with trailing spaces. In the case where an 
E.164 address is to be displayed that is padded with 'f's please
replace the padding with trailing spaces.
.DE
.PP 
.SH Routines
.DS
  
   Procedure:   CiTRCvtIpChar
  
   Description: Convert an IP address to a string
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
  
   Globals:     None
  
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtE164Char
  
   Description: Convert an E164 address to a string
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtPhysChar
  
   Description: Convert a physical address (a octet string) to a characters
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtMACChar
  
   Description: Convert a 802.3 address to a string
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtCPIpChar
  
   Description: Convert an IP address stored as just a 4 octet string 
                (rather than an Openview type) to a character string.
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtCharIp
  
   Description: Convert a string to an IP address.
                Since HP have written this already, just call them and
                translate the return status to fit in.
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtCharE164
  
   Description: Convert an E.164 address to an encoded 8 octet 
                sequence according to the description provided 
                by CP
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtCharPhys
  
   Description: convert a character string to a physical address 
                (octet stream) We have a problem if the input 
                string has an odd length, which means there is 
                a nibble missing. I will assume there is a
                leading 0
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE
.PP .DS
  
   Procedure:   CiTRCvtCharMAC
  
   Description: convert a character string to an 802.3 address
  
   Return:      TRUE on success, else FALSE
  
   Parameters:  None
       
   Globals:     None
       
   Side Effect: None
  
.DE

.SH Examples
See the UNIT_TEST code near the end of citr_cvt.c
.SH SEE ALSO
iptoint(1)
.SH Known Bugs
None
.SH Author
David Horton \- CiTR
.SH Copyright
Centre for Information Technology Research, 1993