src/support/linkback/LinkBack.h

   1 //
   2 //  LinkBack.h
   3 //  LinkBack Project
   4 //
   5 //  Created by Charles Jolley on Tue Jun 15 2004.
   6 //  Copyright (c) 2004, Nisus Software, Inc.
   7 //  All rights reserved.
   8
   9 //  Redistribution and use in source and binary forms, with or without
  10 //  modification, are permitted provided that the following conditions are met:
  11 //
  12 //  Redistributions of source code must retain the above copyright notice,
  13 //  this list of conditions and the following disclaimer.
  14 //
  15 //  Redistributions in binary form must reproduce the above copyright notice,
  16 //  this list of conditions and the following disclaimer in the documentation
  17 //  and/or other materials provided with the distribution.
  18 //
  19 //  Neither the name of the Nisus Software, Inc. nor the names of its
  20 //  contributors may be used to endorse or promote products derived from this
  21 //  software without specific prior written permission.
  22 //
  23 //  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  24 //  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  25 //  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  26 //  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  27 //  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  28 //  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  29 //  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30 //  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31 //  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32 //  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33 //  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34 //
  35
  36
  37 #import <Cocoa/Cocoa.h>
  38
  39 // Use this pasteboard type to put LinkBack data to the pasteboard.  Use MakeLinkBackData() to create the data.
  40 extern NSString* LinkBackPboardType ;
  41
  42 // Default Action Names.  These will be localized for you automatically.
  43 extern NSString* LinkBackEditActionName ;
  44 extern NSString* LinkBackRefreshActionName ;
  45
  46 //
  47 // Support Functions
  48 //
  49 NSString* LinkBackUniqueItemKey() ;
  50 NSString* LinkBackEditMultipleMenuTitle() ;
  51 NSString* LinkBackEditNoneMenuTitle() ;
  52
  53 //
  54 // Deprecated Support Functions -- use LinkBack Data Category instead
  55 //
  56 id MakeLinkBackData(NSString* serverName, id appData) ;
  57 id LinkBackGetAppData(id linkBackData) ;
  58 BOOL LinkBackDataBelongsToActiveApplication(id data) ;
  59
  60 //
  61 // LinkBack Data Category
  62 //
  63
  64 // Use these methods to create and access linkback data objects.  You can also use the helper functions above.
  65
  66 @interface NSDictionary (LinkBackData)
  67
  68 + (NSDictionary*)linkBackDataWithServerName:(NSString*)serverName appData:(id)appData ;
  69
  70 + (NSDictionary*)linkBackDataWithServerName:(NSString*)serverName appData:(id)appData suggestedRefreshRate:(NSTimeInterval)rate ;
  71
  72 + (NSDictionary*)linkBackDataWithServerName:(NSString*)serverName appData:(id)appData actionName:(NSString*)action suggestedRefreshRate:(NSTimeInterval)rate ;
  73
  74 - (BOOL)linkBackDataBelongsToActiveApplication ;
  75
  76 - (id)linkBackAppData ;
  77 - (NSString*)linkBackSourceApplicationName ;
  78 - (NSString*)linkBackActionName ;
  79 - (NSString*)linkBackVersion ;
  80 - (NSURL*)linkBackApplicationURL ;
  81
  82 - (NSTimeInterval)linkBackSuggestedRefreshRate ;
  83
  84 - (NSString*)linkBackEditMenuTitle ;
  85
  86 @end
  87
  88 //
  89 // Delegate Protocols
  90 //
  91
  92 @class LinkBack ;
  93
  94 @protocol LinkBackServerDelegate
  95 - (void)linkBackDidClose:(LinkBack*)link ;
  96 - (void)linkBackClientDidRequestEdit:(LinkBack*)link ;
  97 @end
  98
  99 @protocol LinkBackClientDelegate
 100 - (void)linkBackDidClose:(LinkBack*)link ;
 101 - (void)linkBackServerDidSendEdit:(LinkBack*)link ;
 102 @end
 103
 104 // used for cross app communications
 105 @protocol LinkBack
 106 - (oneway void)remoteCloseLink ;
 107 - (void)requestEditWithPasteboardName:(bycopy NSString*)pboardName ; // from client
 108 - (void)refreshEditWithPasteboardName:(bycopy NSString*)pboardName ; // from server
 109 @end
 110
 111 @interface LinkBack : NSObject <LinkBack> {
 112     LinkBack* peer ; // the client or server on the other side.
 113     BOOL isServer ;
 114     id delegate ;
 115     NSPasteboard* pboard ;
 116     id repobj ;
 117     NSString* sourceName ;
 118         NSString* sourceApplicationName ;
 119     NSString* key ;
 120 }
 121
 122 + (LinkBack*)activeLinkBackForItemKey:(id)key ;
 123 // works for both the client and server side.  Valid only while a link is connected.
 124
 125 // ...........................................................................
 126 // General Use methods
 127 //
 128 - (NSPasteboard*)pasteboard ;
 129 - (void)closeLink ;
 130
 131 - (id)representedObject ;
 132 - (void)setRepresentedObject:(id)obj ;
 133 // Applications can use this represented object to attach some meaning to the live link.  For example, a client application may set this to the object to be modified when the edit is refreshed.  This retains its value.
 134
 135 - (NSString*)sourceName ;
 136 - (NSString*)sourceApplicationName ;
 137 - (NSString*)itemKey ; // maybe this matters only on the client side.
 138
 139 // ...........................................................................
 140 // Server-side methods
 141 //
 142 + (BOOL)publishServerWithName:(NSString*)name delegate:(id<LinkBackServerDelegate>)del ;
 143
 144 + (void)retractServerWithName:(NSString*)name ;
 145
 146 - (void)sendEdit ;
 147
 148 // ...........................................................................
 149 // Client-Side Methods
 150 //
 151 + (LinkBack*)editLinkBackData:(id)data sourceName:(NSString*)aName delegate:(id<LinkBackClientDelegate>)del itemKey:(NSString*)aKey ;
 152
 153 @end
 154
 155 @interface LinkBack (InternalUseOnly)
 156
 157 - (id)initServerWithClient: (LinkBack*)aLinkBack delegate: (id<LinkBackServerDelegate>)aDel ;
 158
 159 - (id)initClientWithSourceName:(NSString*)aName delegate:(id<LinkBackClientDelegate>)aDel itemKey:(NSString*)aKey ;
 160
 161 - (BOOL)connectToServerWithName:(NSString*)aName inApplication:(NSString*)bundleIdentifier fallbackURL:(NSURL*)url appName:(NSString*)appName ;
 162
 163 - (void)requestEdit ;
 164
 165 @end