.\" ident @(#)messages.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH messages 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2messages\fP, \f2messages_byname\fP \ - Messaging facets. .SH SYNOPSIS .br #include .br class messages_base; .br template class messages; .SH DESCRIPTION messages_gives access to a localized messaging facility. The messages facet is used with the "C" locale, while the_messages_byname facet is used with named locales. The messages_base class includes a catalog type for use by the derived messages and messages_byname classes. Note that the default messages facet uses \f2catopen, catclose\fP, etc., to implement the message database. If your platform does not support these, then you need to imbue your own messages facet by implementing whatever database is available. .SH INTERFACE .br class messages_base { .br public: .RE .RS 1 typedef int catalog; .RE .RS 0 }; .br .br template .br class messages : public locale::facet, public messages_base { .br public: .RE .RS 1 typedef charT char_type; .br typedef basic_string string_type; .br explicit messages(size_t = 0); .br catalog open(const basic_string&, const locale&) .RE .RS 14 const; .RE .RS 1 string_type get(catalog, int, int, .RE .RS 17 const string_type&) const; .RE .RS 1 void close(catalog) const; .br static locale::id id; .RE .RS 0 protected: .RE .RS 2 ~messages(); // virtual .RE .RS 1 virtual catalog do_open(const basic_string&, .RE .RS 25 const locale&) const; .RE .RS 1 virtual string_type do_get(catalog, int, int, .RE .RS 29 const string_type&) const; .RE .RS 1 virtual void do_close(catalog) const; .RE .RS 0 }; .br .br class messages_byname : public messages { .br public: .RE .RS 1 explicit messages_byname(const char*, size_t = 0); .RE .RS 0 protected: .RE .RS 2 ~messages_byname(); // virtual .RE .RS 1 virtual catalog do_open(const basic_string&, .RE .RS 25 const locale&) const; .RE .RS 0 virtual string_type do_get(catalog, int, int, .RE .RS 26 const string_type&) const; .RE .RS 1 virtual void do_close(catalog) const; .RE .RS 0 }; .SH TYPES .br char_type .RE .RS 3 Type of character the facet is instantiated on. .RE .br string_type .RE .RS 3 Type of character string returned by member functions. .RE .SH CONSTRUCTORS .br explicit messages(size_t refs = 0) .RE .RS 3 Constructs a messages facet. If the \f2refs\fP argument is \f20\fP, then destruction of the object is delegated to the locale, or locales, containing it. This allows the user to ignore lifetime management issues. On the other hand, if \f2refs\fP is \f21\fP, then the object must be explicitly deleted because the locale does not do so. .RE .br explicit messages_byname(const char* name, .RE .RS 2 size_t refs = 0); .RE .RS 3 Constructs a messages_byname facet. Uses the named locale specified by the name argument. The \f2refs\fP argument serves the same purpose as it does for the messages constructor. .RE .SH DESTRUCTORS .RE .RS 0 ~messages(); // virtual and protected .RE .RS 3 Destroys the facet. .RE .SH FACET ID .br static locale::id id; .RE .RS 3 Unique identifier for this type of facet. .RE .SH PUBLIC MEMBER FUNCTIONS The public members of the messages facet include an interface to protected members. Each public member \f2xxx\fP has a corresponding virtual protected member \f2do_xxx\fP. All work is delegated to these protected members. For instance, the long version of the public \f2open\fP function simply calls its protected cousin \f2do_open\fP. .br void .br close(catalog c) const; .br string_type .br get(catalog c, int set, int msgid, .RE .RS 3 const string_type& dfault) const; .RE .RS 0 catalog .br open(const basic_string& fn, const locale&) const; .RE .RS 3 Each of these public member functions \f2xxx\fP simply call the corresponding protected \f2do_xxx\fP function. .RE .SH PROTECTED MEMBER FUNCTIONS .br virtual void .br do_close(catalog cat) const; .RE .RS 3 Closes the catalog. The \f2cat\fP argument must be obtained by a call to \f2open()\fP. .RE .br virtual string_type .br do_get(catalog cat, int set, int msgid, .RE .RS 6 const string_type& dfault) const; .RE .RS 3 Retrieves a specific message. Returns the message identified by \f2cat\fP, \f2set\fP, \f2msgid\fP, and \f2dfault\fP. \f2cat\fP must be obtained by a previous call to \f2open()\fP. This function must not be called with a \f2cat\fP that has had close called on it after the last call to \f2open()\fP. That is, the catalog must be open and not yet closed. .RE .RE .RS 0 virtual catalog .br do_open(const basic_string& name, const locale&) const; .RE .RS 3 Opens a message catalog. Returns a catalog identifier that can be passed to the\f2 get()\fP function in order to access specific messages. Returns \f2-1\fP if the catalog name specified in the \f2name\fP argument is invalid. The \f2loc\fP argument is used for codeset conversion if necessary. .RE .SH EXAMPLE .br // .br // messages.cpp .br // .br #include .br #include .br .br int main () .br { .RE .RS 1 using namespace std; .RE .RS 0 .RE .RS 1 locale loc; .RE .RS 0 .RE .RS 2 // Get a reference to the messages facet .RE .RS 1 const messages& mess = .RE .RS 0 #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE .RE .RS 3 use_facet >(loc); .RE .RS 0 #else .RE .RS 3 use_facet(loc,(messages*)0); .RE .RS 0 #endif .br .RE .RS 2 // Open a catalog and try to grab .br // both some valid messages, and an invalid message .RE .RS 1 string def("Message Not Found"); .br messages::catalog cat = .RE .RS 9 mess.open("./rwstdmessages.cat",loc); .RE .RS 1 if (cat != -1) .RE .RS 2 { .RE .RS 3 string msg0 = mess.get(cat,1,1,def); .br string msg1 = mess.get(cat,1,2,def); .br string msg2 = mess.get(cat,1,6,def); // invalid msg # .br string msg3 = mess.get(cat,2,1,def); .RE .RS 0 .RE .RS 3 mess.close(cat); .br cout << msg0 << endl << msg1 << endl .RE .RS 9 << msg2 << endl << msg3 << endl; .RE .RS 2 } .RE .RS 1 else .RE .RS 3 cout << "Unable to open message catalog" << endl; .RE .RS 0 .RE .RS 1 return 0; .RE .RS 0 } .SH SEE ALSO locale, facets