src/hg/inc/cart.h 1.46

Index: src/hg/inc/cart.h
===================================================================
RCS file: /projects/compbio/cvsroot/kent/src/hg/inc/cart.h,v
retrieving revision 1.45
retrieving revision 1.46
diff -b -B -U 1000000 -r1.45 -r1.46
--- src/hg/inc/cart.h	19 Mar 2009 21:02:34 -0000	1.45
+++ src/hg/inc/cart.h	19 Aug 2009 18:16:34 -0000	1.46
@@ -1,496 +1,496 @@
 /* cart - stuff to manage variables that persist from
  * one invocation of a cgi script to another (variables
  * that are carted around).  */
 
 #ifndef CART_H
 #define CART_H
 
 #include "jksql.h"
 #include "errabort.h"
 #include "dystring.h"
 #include "linefile.h"
 #include "trackDb.h"
 
 typedef struct sqlConnection *(*DbConnector)();
 /* funtion type used to get a connection to database */
 
 typedef void (*DbDisconnect)(struct sqlConnection **pConn);
 /* function type used to cleanup a connection from database */
 
 
 struct cart
 /* A cart of settings that persist. */
    {
    struct cart *next;	/* Next in list. */
    unsigned int userId;	/* User ID in database. */
    unsigned int sessionId;	/* Session ID in database. */
    struct hash *hash;	/* String valued hash. */
    struct hash *exclude;	/* Null valued hash of variables not to save. */
    struct cartDb *userInfo;	/* Info on user. */
    struct cartDb *sessionInfo;	/* Info on session. */
    };
 
 char *_cartVarDbName(char *db, char *var);
 /* generate cart variable name that is local to an assembly database.
  * Only for use inside of cart.h.  WARNING: static return */
 
 boolean cartTablesOk(struct sqlConnection *conn);
 /* Return TRUE if cart tables are accessible (otherwise, the connection
  * doesn't do us any good). */
 
 struct cart *cartNew(unsigned int userId, unsigned int sessionId,
 	char **exclude, struct hash *oldVars);
 /* Load up cart from user & session id's.  Exclude is a null-terminated list of
  * strings to not include. oldVars is an optional hash to put in values
  * that were just overwritten by cgi-variables. */
 
 struct cart *cartNewEmpty(unsigned int userId, unsigned int sessionId,
 	char **exclude, struct hash *oldVars);
 /* Create a new empty cart structure without reading from the database. */
 
 void cartCheckout(struct cart **pCart);
 /* Save cart to database and free it up. */
 
 void cartEncodeState(struct cart *cart, struct dyString *dy);
 /* Add a CGI-encoded var=val&... string of all cart variables to dy. */
 
 char *cartSessionVarName();
 /* Return name of CGI session ID variable. */
 
 unsigned int cartSessionId(struct cart *cart);
 /* Return session id. */
 
 char *cartSidUrlString(struct cart *cart);
 /* Return session id string as in hgsid=N . */
 
 unsigned int cartUserId(struct cart *cart);
 /* Return session id. */
 
 void cartRemove(struct cart *cart, char *var);
 /* Remove variable from cart. */
 
 void cartRemoveExcept(struct cart *cart, char **except);
 /* Remove variables except those in null terminated except array
  * from cart.  Except array may be NULL in which case all
  * are removed. */
 
 void cartRemoveLike(struct cart *cart, char *wildCard);
 /* Remove all variable from cart that match wildCard. */
 
 void cartRemovePrefix(struct cart *cart, char *prefix);
 /* Remove variables with given prefix from cart. */
 
 boolean cartVarExists(struct cart *cart, char *var);
 /* Return TRUE if variable is in cart. */
 
 INLINE boolean cartVarExistsDb(struct cart *cart, char *db, char *var)
 /* Return TRUE if variable_$db is in cart. */
 {
-    return cartVarExists(cart, _cartVarDbName(db, var));
+return cartVarExists(cart, _cartVarDbName(db, var));
 }
 
 char *cartString(struct cart *cart, char *var);
 /* Return string valued cart variable. */
 
 INLINE char *cartStringDb(struct cart *cart, char *db, char *var)
 /* Return string valued cart var_$db. */
 {
-    return cartString(cart, _cartVarDbName(db, var));
+return cartString(cart, _cartVarDbName(db, var));
 }
 
 char *cartOptionalString(struct cart *cart, char *var);
 /* Return string valued cart variable or NULL if it doesn't exist. */
 
 INLINE char *cartOptionalStringDb(struct cart *cart, char *db, char *var)
 /* Return string valued cart variable_$db or NULL if it doesn't exist. */
 {
-    return cartOptionalString(cart, _cartVarDbName(db, var));
+return cartOptionalString(cart, _cartVarDbName(db, var));
 }
 
 char *cartNonemptyString(struct cart *cart, char *name);
 /* Return string value associated with name.  Return NULL
  * if value doesn't exist or if it is pure white space. */
 
 INLINE char *cartNonemptyStringDb(struct cart *cart, char *db, char *name)
 /* Return string value associated with name_$db.  Return NULL
  * if value doesn't exist or if it is pure white space. */
 {
-    return cartNonemptyString(cart, _cartVarDbName(db, name));
+return cartNonemptyString(cart, _cartVarDbName(db, name));
 }
 
 char *cartUsualString(struct cart *cart, char *var, char *usual);
 /* Return variable value if it exists or usual if not. */
 
 INLINE char *cartUsualStringDb(struct cart *cart, char *db, char *var, char *usual)
 /* Return var_$db value if it exists or usual if not. */
 {
-    return cartUsualString(cart, _cartVarDbName(db, var), usual);
+return cartUsualString(cart, _cartVarDbName(db, var), usual);
 }
 
 char *cartCgiUsualString(struct cart *cart, char *var, char *usual);
 /* Look for var in CGI, then in cart, if not found then return usual. */
 
 struct slName *cartOptionalSlNameList(struct cart *cart, char *var);
 /* Return slName list (possibly with multiple values for the same var) or
  * NULL if not found. */
 
 void cartAddString(struct cart *cart, char *var, char *val);
 /* Add string valued cart variable (if called multiple times on same var,
  * will create a list -- retrieve with cartOptionalSlNameList. */
 
 void cartSetString(struct cart *cart, char *var, char *val);
 /* Set string valued cart variable. */
 
 INLINE void cartSetStringDb(struct cart *cart, char *db, char *var, char *val)
 /* Set string valued cart var_$db. */
 {
-    return cartSetString(cart, _cartVarDbName(db, var), val);
+cartSetString(cart, _cartVarDbName(db, var), val);
 }
 
 int cartInt(struct cart *cart, char *var);
 /* Return int valued variable. */
 
 INLINE int cartIntDb(struct cart *cart, char *db, char *var)
 /* Return int valued variable_$db. */
 {
-    return cartInt(cart, _cartVarDbName(db, var));
+return cartInt(cart, _cartVarDbName(db, var));
 }
 
 
 int cartIntExp(struct cart *cart, char *var);
 /* Return integer valued expression in variable. */
 
 int cartUsualInt(struct cart *cart, char *var, int usual);
 /* Return variable value if it exists or usual if not. */
 
 INLINE int cartUsualIntDb(struct cart *cart, char *db, char *var, int usual)
 /* Return variable_$db value if it exists or usual if not. */
 {
-    return cartUsualInt(cart, _cartVarDbName(db, var), usual);
+return cartUsualInt(cart, _cartVarDbName(db, var), usual);
 }
 
 int cartUsualIntClipped(struct cart *cart, char *var, int usual,
 	int minVal, int maxVal);
 /* Return integer variable clipped to lie between minVal/maxVal */
 
 int cartCgiUsualInt(struct cart *cart, char *var, int usual);
 /* Look for var in CGI, then in cart, if not found then return usual. */
 
 void cartSetInt(struct cart *cart, char *var, int val);
 /* Set integer value. */
 
 INLINE void cartSetIntDb(struct cart *cart, char *db, char *var, int val)
 /* Set integer value for var_$db. */
 {
-    return cartSetInt(cart, _cartVarDbName(db, var), val);
+cartSetInt(cart, _cartVarDbName(db, var), val);
 }
 
 double cartDouble(struct cart *cart, char *var);
 /* Return double valued variable. */
 
 INLINE double cartDoubleDb(struct cart *cart, char *db, char *var)
 /* Return double valued var_$db. */
 {
-    return cartDouble(cart, _cartVarDbName(db, var));
+return cartDouble(cart, _cartVarDbName(db, var));
 }
 
 double cartUsualDouble(struct cart *cart, char *var, double usual);
 /* Return variable value if it exists or usual if not. */
 
 INLINE double cartUsualDoubleDb(struct cart *cart, char *db, char *var, double usual)
 /* Return var_$db value if it exists or usual if not. */
 {
-    return cartUsualDouble(cart, _cartVarDbName(db, var), usual);
+return cartUsualDouble(cart, _cartVarDbName(db, var), usual);
 }
 
 double cartCgiUsualDouble(struct cart *cart, char *var, double usual);
 /* Look for var in CGI, then in cart, if not found then return usual. */
 
 void cartSetDouble(struct cart *cart, char *var, double val);
 /* Set double value. */
 
 INLINE void cartSetDoubleDb(struct cart *cart, char *db, char *var, double val)
 /* Set double value for var_$db. */
 {
-    return cartSetDouble(cart, _cartVarDbName(db, var), val);
+cartSetDouble(cart, _cartVarDbName(db, var), val);
 }
 
 boolean cartBoolean(struct cart *cart, char *var);
 /* Retrieve cart boolean. */
 
 INLINE boolean cartBooleanDb(struct cart *cart, char *db, char *var)
 /* Retrieve cart boolean for var_$db. */
 {
-    return cartBoolean(cart, _cartVarDbName(db, var));
+return cartBoolean(cart, _cartVarDbName(db, var));
 }
 
 boolean cartUsualBoolean(struct cart *cart, char *var, boolean usual);
 /* Return variable value if it exists or usual if not.  */
 
 INLINE boolean cartUsualBooleanDb(struct cart *cart, char *db, char *var, boolean usual)
 /* Return var_$db value if it exists or usual if not.  */
 {
-    return cartUsualBoolean(cart, _cartVarDbName(db, var), usual);
+return cartUsualBoolean(cart, _cartVarDbName(db, var), usual);
 }
 
 boolean cartCgiUsualBoolean(struct cart *cart, char *var, boolean usual);
 /* Look for var in CGI, then in cart, if not found then return usual. */
 
 void cartSetBoolean(struct cart *cart, char *var, boolean val);
 /* Set boolean value. */
 
 INLINE void cartSetBooleanDb(struct cart *cart, char *db, char *var, boolean val)
 /* Set boolean value for $var_db. */
 {
-    return cartSetBoolean(cart, _cartVarDbName(db, var), val);
+cartSetBoolean(cart, _cartVarDbName(db, var), val);
 }
 
 void cartMakeTextVar(struct cart *cart, char *var, char *defaultVal, int charSize);
 /* Make a text control filled with value from cart if it exists or
  * default value otherwise.  If charSize is zero it's calculated to fit
  * current value.  Default value may be NULL. */
 
 void cartMakeIntVar(struct cart *cart, char *var, int defaultVal, int maxDigits);
 /* Make a text control filled with integer value - from cart if available
  * otherwise default.  */
 
 void cartMakeDoubleVar(struct cart *cart, char *var, double defaultVal, int maxDigits);
 /* Make a text control filled with integer value - from cart if available
  * otherwise default.  */
 
 void cartMakeCheckBox(struct cart *cart, char *var, boolean defaultVal);
 /* Make a check box filled with value from cart if it exists or
  * default value otherwise.  */
 
 void cartMakeRadioButton(struct cart *cart, char *var, char *val, char *defaultVal);
 /* Make a radio button that is selected if cart variable exists and matches
  * value (or value matches default val if cart var doesn't exist). */
 
 void cartSaveSession(struct cart *cart);
 /* Save session in a hidden variable. This needs to be called
  * somewhere inside of form or bad things will happen. */
 
 void cartDump(struct cart *cart);
 /* Dump contents of cart. */
 
 void cartDumpList(struct hashEl *elList);
 /* Dump list of cart variables. */
 
 void cartDumpPrefix(struct cart *cart, char *prefix);
 /* Dump all cart variables with prefix */
 
 void cartDumpLike(struct cart *cart, char *wildcard);
 /* Dump all cart variables matching wildcard */
 
 struct hashEl *cartFindPrefix(struct cart *cart, char *prefix);
 /* Return list of name/val pairs from cart where name starts with
  * prefix.  Free when done with hashElFreeList. */
 
 struct hashEl *cartFindLike(struct cart *cart, char *wildCard);
 /* Return list of name/val pairs from cart where name matches
  * wildcard.  Free when done with hashElFreeList. */
 
 char *cartFindFirstLike(struct cart *cart, char *wildCard);
 /* Find name of first variable that matches wildCard in cart.
  * Return NULL if none. */
 
 void cartResetInDb(char *cookieName);
 /* Clear cart in database. */
 
 void cartEarlyWarningHandler(char *format, va_list args);
 /* Write an error message so user can see it before page is really started */
 
 void cartWarnCatcher(void (*doMiddle)(struct cart *cart), struct cart *cart, WarnHandler warner);
 /* Wrap error and warning handlers around doMiddl. */
 
 void cartEmptyShell(void (*doMiddle)(struct cart *cart), char *cookieName,
 	char **exclude, struct hash *oldVars);
 /* Get cart and cookies and set up error handling, but don't start writing any
  * html yet. The doMiddleFunction has to call cartHtmlStart(title), and
  * cartHtmlEnd(), as well as writing the body of the HTML.
  * oldVars - those in cart that are overlayed by cgi-vars are
  * put in optional hash oldVars. */
 
 void cartHtmlStart(char *title);
 /* Write HTML header and put in normal error handler. Needed with cartEmptyShell,
  * but not cartHtmlShell. */
 
 void cartFooter(void);
 /* Write out HTML footer, possibly with googleAnalytics too */
 
 void cartHtmlEnd();
 /* Write out HTML footer and get rid or error handler. Needed with cartEmptyShell,
  * but not cartHtmlShell. */
 
 void cartWebStart(struct cart *theCart, char *db, char *format, ...)
 /* Print out pretty wrapper around things when working
  * from cart. Balance this with cartWebEnd. */
 #if defined(__GNUC__)
 __attribute__((format(printf, 3, 4)))
 #endif
 ;
 
 void cartVaWebStart(struct cart *cart, char *db, char *format, va_list args);
 /* Print out pretty wrapper around things when working
  * from cart. */
 
 void cartWebEnd();
 /* End out pretty wrapper around things when working
  * from cart. */
 
 void cartHtmlShellWithHead(char *head, char *title, void (*doMiddle)(struct cart *cart),
         char *cookieName, char **exclude, struct hash *oldVars);
 /* Load cart from cookie and session cgi variable.  Write web-page
  * preamble including head and title, call doMiddle with cart, and write end of web-page.
  * Exclude may be NULL.  If it exists it's a comma-separated list of
  * variables that you don't want to save in the cart between
  * invocations of the cgi-script. */
 
 void cartHtmlShell(char *title, void (*doMiddle)(struct cart *cart),
 	char *cookieName, char **exclude, struct hash *oldVars);
 /* Load cart from cookie and session cgi variable.  Write web-page preamble, call doMiddle
  * with cart, and write end of web-page.   Exclude may be NULL.  If it exists it's a
  * comma-separated list of variables that you don't want to save in the cart between
  * invocations of the cgi-script. oldVars is an optional hash that will get values
  * of things in the cart that were overwritten by cgi-variables. */
 
 void cartHtmlShellPB(char *title, void (*doMiddle)(struct cart *cart),
         char *cookieName, char **exclude, struct hash *oldVars);
 /* For Proteome Browser, load cart from cookie and session cgi variable.  Write web-page
  * preamble, call doMiddle with cart, and write end of web-page.
  * Exclude may be NULL.  If it exists it's a comma-separated list of
  * variables that you don't want to save in the cart between
  * invocations of the cgi-script. */
 
 void cartHtmlShellPbGlobal(char *title, void (*doMiddle)(struct cart *cart),
         char *cookieName, char **exclude, struct hash *oldVars);
 /* For Proteome Browser, load cart from cookie and session cgi variable.  Write web-page
  * preamble, call doMiddle with cart, and write end of web-page.
  * Exclude may be NULL.  If it exists it's a comma-separated list of
  * variables that you don't want to save in the cart between
  * invocations of the cgi-script. */
 
 void cartWriteCookie(struct cart *cart, char *cookieName);
 /* Write out HTTP Set-Cookie statement for cart. */
 
 struct cart *cartAndCookie(char *cookieName, char **exclude,
 	struct hash *oldVars);
 /* Load cart from cookie and session cgi variable.  Write cookie and
  * content-type part HTTP preamble to web page.  Don't write any HTML though. */
 
 struct cart *cartAndCookieNoContent(char *cookieName, char **exclude,
 	struct hash *oldVars);
 /* Load cart from cookie and session cgi variable. Don't write out
  * content type or any HTML. */
 
 struct cart *cartAndCookieWithHtml(char *cookieName, char **exclude,
 	struct hash *oldVars, boolean doContentType);
 /* Load cart from cookie and session cgi variable.  Write cookie
  * and optionally content-type part HTTP preamble to web page.  Don't
  * write any HTML though. */
 
 struct cart *cartForSession(char *cookieName, char **exclude,
 	struct hash *oldVars);
 /* This gets the cart without writing any HTTP lines at all to stdout. */
 
 void cartSetDbConnector(DbConnector connector);
 /* Set the connector that will be used by the cart to connect to the
  * database. Default connector is hConnectCart */
 
 void cartSetDbDisconnector(DbDisconnect disconnector);
 /* Set the connector that will be used by the cart to disconnect from the
  * database. Default disconnector is hDisconnectCart */
 
 
 /* Libified constants and code that originally belonged only to hgSession
  * (now hgTracks uses them too): */
 #define hgSessionPrefix "hgS_"
 
 #define hgsOtherUserName hgSessionPrefix "otherUserName"
 #define hgsOtherUserSessionName hgSessionPrefix "otherUserSessionName"
 #define hgsDoOtherUser hgSessionPrefix "doOtherUser"
 
 #define hgsLoadUrlName hgSessionPrefix "loadUrlName"
 #define hgsDoLoadUrl hgSessionPrefix "doLoadUrl"
 
 #define namedSessionTable "namedSessionDb"
 
 void sessionTouchLastUse(struct sqlConnection *conn, char *encUserName,
 			 char *encSessionName);
 /* Increment namedSessionDb.useCount and update lastUse for this session. */
 
 void cartLoadUserSession(struct sqlConnection *conn, char *sessionOwner,
 			 char *sessionName, struct cart *cart,
 			 struct hash *oldVars, char *actionVar);
 /* If permitted, load the contents of the given user's session, and then
  * reload the CGI settings (to support override of session settings).
  * If non-NULL, oldVars will contain values overloaded when reloading CGI.
  * If non-NULL, actionVar is a cartRemove wildcard string specifying the
  * CGI action variable that sent us here. */
 
 void cartLoadSettings(struct lineFile *lf, struct cart *cart,
 		      struct hash *oldVars, char *actionVar);
 /* Load settings (cartDump output) into current session, and then
  * reload the CGI settings (to support override of session settings).
  * If non-NULL, oldVars will contain values overloaded when reloading CGI.
  * If non-NULL, actionVar is a cartRemove wildcard string specifying the
  * CGI action variable that sent us here. */
 
 char *cartGetOrderFromFile(char *genomeDb, struct cart *cart, char *speciesUseFile);
 /* Look in a cart variable that holds the filename that has a list of
  * species to show in a maf file */
 
 char *cartGetOrderFromFileAndMsaTable(char *genomeDb, struct cart *cart, char *speciesUseFile, char *msaTable);
 /* Look in a cart variable that holds the filename that has a list of
  * species to show in a maf file */
 
 char *cartLookUpVariableClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix,char **pVariable);
 /* Returns value or NULL for a cart variable from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix
    Optionally fills the non NULL pVariable with the actual name of the variable in the cart */
 #define cartOptionalStringClosestToHome(cart,tdb,compositeLevel,suffix) cartLookUpVariableClosestToHome((cart),(tdb),(compositeLevel),(suffix),NULL)
 
 void cartRemoveVariableClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix);
 /* Looks for then removes a cart variable from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 char *cartStringClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix);
 /* Returns value or Aborts for a cart string from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 boolean cartVarExistsAnyLevel(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix);
 /* Returns TRUE if variable exists anywhere, looking from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 char *cartUsualStringClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix, char *usual);
 /* Returns value or {usual} for a cart string from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 boolean cartBooleanClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix);
 /* Returns value or Aborts for a cart boolean ('on' or != 0) from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 boolean cartUsualBooleanClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix,boolean usual);
 /* Returns value or {usual} for a cart boolean ('on' or != 0) from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 int cartUsualIntClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix, int usual);
 /* Returns value or {usual} for a cart int from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 double cartUsualDoubleClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix, double usual);
 /* Returns value or {usual} for a cart fp double from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 struct slName *cartOptionalSlNameListClosestToHome(struct cart *cart, struct trackDb *tdb, boolean compositeLevel, char *suffix);
 /* Return slName list (possibly with multiple values for the same var) from lowest level on up:
    subtrackName.suffix, then compositeName.view.suffix, then compositeName.suffix */
 
 void cartRemoveAllForTdb(struct cart *cart, struct trackDb *tdb);
 /* Remove all variables from cart that are associated with this tdb. */
 
 void cartRemoveAllForTdbAndChildren(struct cart *cart, struct trackDb *tdb);
 /* Remove all variables from cart that are associated
    with this tdb and it's children. */
 #endif /* CART_H */